@codyswann/lisa 4.74.9 → 4.75.1

package/plugins/lisa-expo-devin/skills/local-state/references/reactive-variables.md

@@ -0,0 +1,446 @@
+# Reactive Variables Reference
+
+## Overview
+
+Reactive variables are Apollo Client 3's mechanism for managing local state outside the GraphQL cache. They enable seamless reactivity without requiring GraphQL syntax and can store any data type.
+
+## Creating Reactive Variables
+
+### Basic Types
+
+```typescript
+import { makeVar } from "@apollo/client";
+
+// Boolean
+export const isLoadingVar = makeVar<boolean>(false);
+
+// String
+export const selectedIdVar = makeVar<string | null>(null);
+
+// Number
+export const countVar = makeVar<number>(0);
+```
+
+### Complex Types
+
+```typescript
+// Interface-based object
+interface IFilterValues {
+  readonly minAge: number;
+  readonly maxAge: number;
+  readonly positions: readonly string[];
+}
+
+const DEFAULT_FILTERS: IFilterValues = {
+  minAge: 18,
+  maxAge: 40,
+  positions: [],
+};
+
+export const filterValuesVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+```
+
+### Record Types for Lookups
+
+```typescript
+// Key-value lookup
+export const selectedPlayersVar = makeVar<Record<string, boolean>>({});
+
+// Complex value lookup
+interface PlayerNote {
+  readonly playerId: string;
+  readonly note: string;
+  readonly updatedAt: string;
+}
+
+export const playerNotesVar = makeVar<Record<string, PlayerNote>>({});
+```
+
+### Array Types
+
+```typescript
+interface Todo {
+  readonly id: string;
+  readonly text: string;
+  readonly completed: boolean;
+}
+
+type Todos = readonly Todo[];
+
+export const todosVar = makeVar<Todos>([]);
+```
+
+## Reading Values
+
+### Direct Read (Non-Reactive)
+
+Call without arguments to read current value. Does NOT trigger component re-renders:
+
+```typescript
+const currentFilters = filterValuesVar();
+const selectedPlayers = selectedPlayersVar();
+```
+
+Use for:
+
+- Event handlers
+- Utility functions
+- Async operations
+- Conditional logic outside JSX
+
+### Reactive Read with Hook
+
+Use `useReactiveVar` for components that should re-render on changes:
+
+```typescript
+import { useReactiveVar } from "@apollo/client";
+
+const FilterDisplay = () => {
+  const filters = useReactiveVar(filterValuesVar);
+
+  return (
+    <View>
+      <Text>Age: {filters.minAge} - {filters.maxAge}</Text>
+      <Text>Positions: {filters.positions.join(", ")}</Text>
+    </View>
+  );
+};
+```
+
+## Updating Values
+
+### Object Updates
+
+Always create new object references:
+
+```typescript
+// Single field update
+filterValuesVar({
+  ...filterValuesVar(),
+  minAge: 21,
+});
+
+// Multiple field update
+filterValuesVar({
+  ...filterValuesVar(),
+  minAge: 21,
+  maxAge: 35,
+});
+
+// Nested object update
+settingsVar({
+  ...settingsVar(),
+  display: {
+    ...settingsVar().display,
+    showGrid: true,
+  },
+});
+```
+
+### Array Updates
+
+```typescript
+// Add item
+todosVar([
+  ...todosVar(),
+  { id: crypto.randomUUID(), text: "New todo", completed: false },
+]);
+
+// Remove item
+todosVar(todosVar().filter(todo => todo.id !== idToRemove));
+
+// Update item
+todosVar(
+  todosVar().map(todo =>
+    todo.id === idToUpdate ? { ...todo, completed: true } : todo
+  )
+);
+
+// Clear all
+todosVar([]);
+```
+
+### Record Updates
+
+```typescript
+// Add/update entry
+selectedPlayersVar({
+  ...selectedPlayersVar(),
+  [playerId]: true,
+});
+
+// Remove entry (using destructuring)
+const { [playerIdToRemove]: _, ...remaining } = selectedPlayersVar();
+selectedPlayersVar(remaining);
+
+// Toggle entry
+const current = selectedPlayersVar();
+selectedPlayersVar({
+  ...current,
+  [playerId]: !current[playerId],
+});
+```
+
+## Custom Hooks Pattern
+
+Encapsulate reactive variable logic in custom hooks for better testability:
+
+```typescript
+import { makeVar, ReactiveVar, useReactiveVar } from "@apollo/client";
+import { useCallback } from "react";
+
+interface IFilterValues {
+  readonly minAge: number;
+  readonly maxAge: number;
+  readonly positions: readonly string[];
+}
+
+const DEFAULT_FILTERS: IFilterValues = {
+  minAge: 18,
+  maxAge: 40,
+  positions: [],
+};
+
+export const filterValuesVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+
+/**
+ * Custom hook for filter operations
+ * Encapsulates all filter state logic
+ */
+export const useFilters = () => {
+  const filters = useReactiveVar(filterValuesVar);
+
+  const setMinAge = useCallback((minAge: number) => {
+    filterValuesVar({ ...filterValuesVar(), minAge });
+  }, []);
+
+  const setMaxAge = useCallback((maxAge: number) => {
+    filterValuesVar({ ...filterValuesVar(), maxAge });
+  }, []);
+
+  const togglePosition = useCallback((position: string) => {
+    const current = filterValuesVar();
+    const hasPosition = current.positions.includes(position);
+    const positions = hasPosition
+      ? current.positions.filter(p => p !== position)
+      : [...current.positions, position];
+    filterValuesVar({ ...current, positions });
+  }, []);
+
+  const resetFilters = useCallback(() => {
+    filterValuesVar(DEFAULT_FILTERS);
+  }, []);
+
+  return {
+    filters,
+    setMinAge,
+    setMaxAge,
+    togglePosition,
+    resetFilters,
+  };
+};
+```
+
+## Dependency Injection for Testing
+
+Pass reactive variables as parameters for testable hooks:
+
+```typescript
+/**
+ * Testable hook with dependency injection
+ * @param filtersVar - Reactive variable (can be mocked in tests)
+ */
+export const useFiltersWithDI = (
+  filtersVar: ReactiveVar<IFilterValues> = filterValuesVar
+) => {
+  const filters = useReactiveVar(filtersVar);
+
+  const setMinAge = useCallback(
+    (minAge: number) => {
+      filtersVar({ ...filtersVar(), minAge });
+    },
+    [filtersVar]
+  );
+
+  return { filters, setMinAge };
+};
+
+// Test usage
+describe("useFiltersWithDI", () => {
+  it("should update minAge", () => {
+    const testVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+    const { result } = renderHook(() => useFiltersWithDI(testVar));
+
+    act(() => {
+      result.current.setMinAge(25);
+    });
+
+    expect(testVar().minAge).toBe(25);
+  });
+});
+```
+
+## Cache Type Policy Integration
+
+Connect reactive variables to GraphQL queries using field policies:
+
+```typescript
+import { InMemoryCache, makeVar } from "@apollo/client";
+import { gql } from "@apollo/client";
+
+// Reactive variable
+export const filterValuesVar = makeVar<IFilterValues>(DEFAULT_FILTERS);
+
+// Cache configuration
+export const cache = new InMemoryCache({
+  typePolicies: {
+    Query: {
+      fields: {
+        filterValues: {
+          read() {
+            return filterValuesVar();
+          },
+        },
+      },
+    },
+  },
+});
+
+// Query local state with @client directive
+export const GET_FILTER_VALUES = gql`
+  query GetFilterValues {
+    filterValues @client {
+      minAge
+      maxAge
+      positions
+    }
+  }
+`;
+
+// Use in component
+const FilterComponent = () => {
+  const { data } = useQuery(GET_FILTER_VALUES);
+  // data.filterValues is reactive
+};
+```
+
+## Performance Considerations
+
+### Split Large State
+
+Instead of one large reactive variable, use multiple smaller ones:
+
+```typescript
+// AVOID - single large state
+const appStateVar = makeVar({
+  user: {
+    /* ... */
+  },
+  settings: {
+    /* ... */
+  },
+  filters: {
+    /* ... */
+  },
+  selectedItems: {
+    /* ... */
+  },
+});
+
+// PREFER - separate concerns
+export const userVar = makeVar<User | null>(null);
+export const settingsVar = makeVar<Settings>(DEFAULT_SETTINGS);
+export const filtersVar = makeVar<Filters>(DEFAULT_FILTERS);
+export const selectedItemsVar = makeVar<Record<string, boolean>>({});
+```
+
+### Batch Related Updates
+
+Update multiple fields in a single call:
+
+```typescript
+// CORRECT - single update
+filterValuesVar({
+  ...filterValuesVar(),
+  minAge: 21,
+  maxAge: 35,
+  positions: ["QB", "WR"],
+});
+
+// AVOID - multiple sequential updates
+filterValuesVar({ ...filterValuesVar(), minAge: 21 });
+filterValuesVar({ ...filterValuesVar(), maxAge: 35 });
+filterValuesVar({ ...filterValuesVar(), positions: ["QB", "WR"] });
+```
+
+### Selector Pattern for Complex State
+
+Create selector wrappers to minimize re-renders:
+
+```typescript
+// Store
+export const allPlayersVar = makeVar<Record<string, Player>>({});
+
+// Selector hook - only re-renders when specific player changes
+export const usePlayer = (playerId: string): Player | undefined => {
+  const allPlayers = useReactiveVar(allPlayersVar);
+  return allPlayers[playerId];
+};
+
+// Component only re-renders when its specific player changes
+const PlayerCard = ({ playerId }: { playerId: string }) => {
+  const player = usePlayer(playerId);
+  return player ? <Text>{player.name}</Text> : null;
+};
+```
+
+## TypeScript Best Practices
+
+### Use Readonly Types
+
+Enforce immutability at the type level:
+
+```typescript
+interface IState {
+  readonly items: readonly Item[];
+  readonly metadata: Readonly<Metadata>;
+}
+
+export const stateVar = makeVar<IState>({
+  items: [],
+  metadata: { count: 0 },
+});
+```
+
+### Use Generic Constraints
+
+```typescript
+// Generic updater function
+const updateVar = <T extends Record<string, unknown>>(
+  reactiveVar: ReactiveVar<T>,
+  updates: Partial<T>
+): void => {
+  reactiveVar({ ...reactiveVar(), ...updates });
+};
+
+// Usage
+updateVar(settingsVar, { theme: "dark" });
+```
+
+### Export Types with Variables
+
+```typescript
+// Export both type and variable
+export interface IFilterValues {
+  readonly minAge: number;
+  readonly maxAge: number;
+}
+
+export const filterValuesVar = makeVar<IFilterValues>({
+  minAge: 18,
+  maxAge: 40,
+});
+
+// Re-export type for consumers
+export type { IFilterValues };
+```

package/plugins/lisa-expo-devin/skills/maestro-mcp-setup/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: maestro-mcp-setup
+description: Enable the Maestro CLI's built-in MCP server (`maestro mcp`, STDIO) for this machine, robustly. Detects the Maestro CLI and a usable Java runtime, installs/guides what is missing, and registers the MCP server at LOCAL (per-machine, uncommitted) scope with an absolute command path and injected JAVA_HOME/PATH so the spawn never dies on a non-login PATH. Use when an Expo project needs Maestro device-automation tools (list_devices, inspect_screen, take_screenshot, run flows). Never registers at project/committed scope — that reintroduces the fleet-wide "-32000" failure.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Maestro MCP Setup
+
+Wire the Maestro CLI's built-in MCP server (`maestro mcp`, STDIO) into the
+current coding agent for **this machine only**, in a way that actually works.
+
+## Why this skill exists (read before changing it)
+
+The Maestro MCP server is intentionally **NOT** in the distributed plugin
+`.mcp.json`. A static, committed entry always attempts to spawn, and coding
+agents spawn stdio servers with a **non-login PATH**. So an always-on entry
+fails visibly — Claude Code shows `Failed to reconnect … -32000` **every
+session** — on any machine missing the Maestro CLI *or* a resolvable Java
+runtime, which is most of a typical fleet (CI runners, unattended QA/intake
+agent boxes). That exact regression shipped once (expo plugin commit b12d5d3)
+and was reverted (b1f3efd).
+
+This skill fixes both failure modes without poisoning the fleet:
+
+1. **Missing CLI / Java** → detect, and install or guide install.
+2. **Installed but PATH-less spawn** → register with an **absolute `command`
+   path** plus injected **`JAVA_HOME` / `PATH`** env, so the server finds Java
+   regardless of the spawn's inherited PATH.
+
+Registration is always **`--scope local`** (per-machine, uncommitted). Never use
+`--scope project` / a committed `.mcp.json` entry — that is the always-on form
+that reds out every other machine.
+
+## Steps
+
+### 1. Locate the Maestro CLI
+
+```bash
+MAESTRO_BIN="$(command -v maestro || true)"
+[ -z "$MAESTRO_BIN" ] && [ -x "$HOME/.maestro/bin/maestro" ] && MAESTRO_BIN="$HOME/.maestro/bin/maestro"
+echo "maestro: ${MAESTRO_BIN:-NOT FOUND}"
+```
+
+If not found, install it (official installer — confirm with the user first,
+since it writes to `~/.maestro`):
+
+```bash
+curl -fsSL "https://get.maestro.mobile.dev" | bash
+MAESTRO_BIN="$HOME/.maestro/bin/maestro"
+```
+
+Resolve to an **absolute** path — a bare `maestro` in the registration relies on
+the very PATH that is missing at spawn time.
+
+### 2. Locate a usable Java runtime
+
+Maestro needs a JDK (8+). Resolve `JAVA_HOME` **honoring the project's version
+manager** — do not install a parallel global JDK when one is already managed:
+
+```bash
+# Prefer an already-active/managed Java before installing anything. Covers the
+# common version managers (mise, asdf, SDKMAN) plus an ambient install.
+if command -v mise >/dev/null 2>&1 && mise which java >/dev/null 2>&1; then
+  JAVA_BIN="$(mise which java)"
+elif command -v asdf >/dev/null 2>&1 && asdf which java >/dev/null 2>&1; then
+  JAVA_BIN="$(asdf which java)"
+elif [ -x "${SDKMAN_DIR:-$HOME/.sdkman}/candidates/java/current/bin/java" ]; then
+  # SDKMAN's `sdk` is a shell function absent in non-login shells; use its stable
+  # `candidates/java/current` symlink directly instead.
+  JAVA_BIN="${SDKMAN_DIR:-$HOME/.sdkman}/candidates/java/current/bin/java"
+elif command -v java >/dev/null 2>&1; then
+  JAVA_BIN="$(command -v java)"
+fi
+echo "java: ${JAVA_BIN:-NOT FOUND}"
+
+# Derive JAVA_HOME by asking the JVM itself — NOT `dirname "$JAVA_BIN"/..`, which
+# is wrong when `java` is a mise/asdf shim or a symlink whose parent is not a JDK
+# root. Fall back to the bin/.. parent only if the JVM query yields nothing usable.
+if [ -n "$JAVA_BIN" ]; then
+  JAVA_HOME="$("$JAVA_BIN" -XshowSettings:properties -version 2>&1 \
+    | sed -n 's/^[[:space:]]*java\.home = //p' | head -n 1)"
+  { [ -z "$JAVA_HOME" ] || [ ! -x "$JAVA_HOME/bin/java" ]; } &&
+    JAVA_HOME="$(cd "$(dirname "$JAVA_BIN")/.." && pwd)"
+fi
+```
+
+If no Java is found: install through the project's version manager when present
+(`mise use -g java@21`, `asdf install java …`, or `sdk install java`), or guide
+the user to install a JDK. Prefer the managed path; only fall back to a global
+install with explicit consent. Re-resolve `JAVA_HOME` afterward.
+
+### 3. Register at local scope with injected env
+
+Build a `PATH` that puts the Maestro and Java `bin` dirs first, then register for
+the **current** coding agent. `$JAVA_BIN`/`$MAESTRO_BIN` are absolute.
+
+Claude Code:
+
+```bash
+# Refuse to register a broken server — both toolchain paths must resolve and be
+# executable, or `claude mcp add` would create the exact -32000 entry this skill
+# exists to avoid.
+[ -n "$MAESTRO_BIN" ] && [ -x "$MAESTRO_BIN" ] || { echo "Maestro CLI unresolved — abort"; exit 1; }
+[ -n "$JAVA_HOME" ] && [ -x "$JAVA_HOME/bin/java" ] || { echo "Java runtime unresolved — abort"; exit 1; }
+
+# Use the real JDK bin (from JAVA_HOME), not the shim dir, on PATH.
+JBIN_DIR="$JAVA_HOME/bin"; MBIN_DIR="$(dirname "$MAESTRO_BIN")"
+claude mcp add --scope local maestro \
+  --env "JAVA_HOME=$JAVA_HOME" \
+  --env "PATH=$JBIN_DIR:$MBIN_DIR:$PATH" \
+  -- "$MAESTRO_BIN" mcp
+```
+
+Parity — same intent on other harnesses (local/per-machine scope, absolute
+command, injected `JAVA_HOME`/`PATH`); translate the registration verb only:
+
+- **Codex** — `codex mcp add maestro --env JAVA_HOME=… --env PATH=… -- "$MAESTRO_BIN" mcp` (writes `~/.codex/config.toml`; keep it out of the committed project config).
+- **Cursor** — add the server to the user-scope `~/.cursor/mcp.json` (not the project `.cursor/mcp.json`) with `command`, `args: ["mcp"]`, and `env: { JAVA_HOME, PATH }`.
+- **OpenCode** — add to the user config (`~/.config/opencode/opencode.json`) `mcp` block with the absolute command and `environment`.
+- **Antigravity (agy) / Copilot** — add to the per-user MCP config with the absolute command + `env`; Copilot uses `type: "local"` for stdio servers.
+
+In every case: **local/user scope, never the committed project file.**
+
+### 4. Verify
+
+```bash
+claude mcp list        # or the harness equivalent
+```
+
+Confirm `maestro` shows connected. If it still fails, the usual cause is
+`JAVA_HOME` pointing at a JRE without `bin/java`, or a Maestro path that moved —
+re-resolve both and re-register. Do not "fix" it by dropping to a bare
+`maestro mcp` command; that reintroduces the PATH-less failure.
+
+## Guardrails
+
+- **Local scope only.** If you catch yourself typing `--scope project` or editing
+  a committed `.mcp.json`, stop — that is the reverted fleet-wide regression.
+- **Absolute paths + injected env are mandatory**, not optional — they are the
+  whole reason this is a skill and not a one-line doc.
+- Installing the CLI or a JDK mutates the machine — confirm before installing,
+  and prefer the project's version manager over a parallel global install.