@ranimontagna/agent-toolkit 0.1.5 → 0.1.7

package/skills/frontend/react/react-testing/rules/react/testing.md

@@ -0,0 +1,208 @@
+---
+paths:
+  - "**/*.test.tsx"
+  - "**/*.test.jsx"
+  - "**/*.spec.tsx"
+  - "**/*.spec.jsx"
+  - "**/__tests__/**/*.ts"
+  - "**/__tests__/**/*.tsx"
+---
+# React Testing
+
+> This file extends the upstream `typescript/testing.md` and `common/testing.md` rules with React specific content.
+
+## Library Choice
+
+- **React Testing Library (RTL)** — the standard for component testing. Tests behavior through the rendered DOM.
+- **Vitest** — preferred runner for new Vite-based projects. Faster than Jest, native ESM, same API.
+- **Jest** — still the default for Next.js / CRA projects. RTL works identically.
+- **Playwright Component Testing** — when component tests need a real browser engine (animation, layout, complex events)
+- **Cypress Component Testing** — alternative real-browser component runner
+
+Pick one component test runner per project — do not mix RTL + Playwright CT in the same repo.
+
+## Core Principle
+
+Test what the user sees and does, not implementation details.
+
+- Query by accessible role first, then label, then text — fall back to `data-testid` only when nothing else fits
+- Never assert on internal state, props passed to children, or which hooks were called
+- Refactor without breaking tests = the test was testing behavior; that is the goal
+
+## Query Priority
+
+RTL exposes queries in three families. Use this priority order top-down:
+
+1. **Accessible to everyone**
+   - `getByRole(role, { name })` — primary choice
+   - `getByLabelText` — for form inputs
+   - `getByPlaceholderText` — when no label is available (and add a label)
+   - `getByText` — for non-interactive text
+   - `getByDisplayValue` — for form fields with a current value
+
+2. **Semantic queries**
+   - `getByAltText` — for images
+   - `getByTitle` — last resort, low accessibility value
+
+3. **Test IDs**
+   - `getByTestId("some-id")` — escape hatch only, when none of the above work
+
+`getBy*` throws when no match. `queryBy*` returns null (use for asserting absence). `findBy*` returns a promise (use for async).
+
+## User Interaction
+
+Prefer `userEvent` over `fireEvent`. `userEvent` simulates real browser sequences (focus, keydown, beforeinput, input, keyup) — `fireEvent` dispatches a single synthetic event.
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+test("submits the form", async () => {
+  const user = userEvent.setup();
+  render(<UserForm onSubmit={handleSubmit} />);
+
+  await user.type(screen.getByLabelText("Email"), "user@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(handleSubmit).toHaveBeenCalledWith({ email: "user@example.com" });
+});
+```
+
+- Always `await` `userEvent` calls — they are async
+- Call `userEvent.setup()` once at the top of each test, then reuse the returned `user`
+
+## Async Assertions
+
+```tsx
+// WRONG: synchronous query for async-rendered content
+expect(screen.getByText("Loaded")).toBeInTheDocument();   // throws — not in DOM yet
+
+// CORRECT: findBy* (returns a promise, retries)
+expect(await screen.findByText("Loaded")).toBeInTheDocument();
+
+// CORRECT: waitFor for non-element assertions
+await waitFor(() => expect(saveSpy).toHaveBeenCalled());
+```
+
+- `findBy*` for async element appearance
+- `waitFor` for async expectations on side effects or other matchers
+- Never `setTimeout` + assertion — flaky
+
+## Network Mocking with MSW
+
+Use Mock Service Worker for any test that hits a network boundary. MSW runs at the network layer, so the component, hooks, and fetch library all behave as in production.
+
+```tsx
+// test setup
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+
+const server = setupServer(
+  http.get("/api/users/:id", ({ params }) =>
+    HttpResponse.json({ id: params.id, name: "Alice" }),
+  ),
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+Per-test override:
+
+```tsx
+test("renders error on 500", async () => {
+  server.use(http.get("/api/users/:id", () => new HttpResponse(null, { status: 500 })));
+  render(<UserPage id="1" />);
+  expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument();
+});
+```
+
+## Avoid Snapshot Tests for Components
+
+Snapshots of rendered output are brittle, hard to review, and rubber-stamped by reviewers. Use them only for:
+
+- Pure data serialization (e.g., a transformer that produces a stable string)
+- Catching unintended regressions in non-visual output
+
+For component visual regression, use Playwright / Cypress / Percy screenshots — actual visual diffs, not DOM diffs.
+
+## Test Setup Helpers
+
+Wrap providers once:
+
+```tsx
+function renderWithProviders(ui: React.ReactElement) {
+  return render(
+    <QueryClientProvider client={new QueryClient()}>
+      <ThemeProvider theme={lightTheme}>
+        <Router>{ui}</Router>
+      </ThemeProvider>
+    </QueryClientProvider>,
+  );
+}
+```
+
+Export from `test-utils.tsx` and use everywhere.
+
+## Custom Hook Testing
+
+Use `renderHook` from RTL:
+
+```tsx
+import { renderHook, act } from "@testing-library/react";
+
+test("useCounter increments", () => {
+  const { result } = renderHook(() => useCounter());
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+});
+```
+
+- Always wrap state-changing calls in `act`
+- Always test through the public hook API, not internal implementation
+
+## Accessibility Assertions
+
+```tsx
+import { axe } from "vitest-axe";   // or jest-axe
+
+test("UserCard has no a11y violations", async () => {
+  const { container } = render(<UserCard user={mockUser} />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Run axe assertions in component tests — catches missing labels, ARIA misuse, color contrast (limited).
+
+## When to Reach for Playwright / Cypress
+
+Component test with RTL + JSDOM cannot:
+
+- Test real layout (flexbox, grid, viewport-dependent rendering)
+- Test scrolling, drag-and-drop, paste from clipboard
+- Test browser-native animation, CSS transitions
+- Test cross-frame interactions (iframes, popups)
+
+For those, use Playwright Component Testing or end-to-end Playwright/Cypress runs. See the e2e-testing skill when it is installed.
+
+## Coverage Targets
+
+| Layer | Target |
+|---|---|
+| Pure utility functions | ≥90% |
+| Custom hooks | ≥85% |
+| Components (presentational) | ≥80% — behavior, not lines |
+| Container components | ≥70% — golden paths + error states |
+| Pages (E2E covered separately) | Smoke test per route minimum |
+
+## Anti-Patterns
+
+- Asserting on `container.querySelector` — bypasses accessibility queries
+- Asserting on number of renders — implementation detail
+- Mocking React hooks (`jest.mock("react", ...)`) — refactor the component instead
+- Mocking child components by default — tests the integration, not the parent in isolation
+- Manual `act()` warnings ignored — they indicate real bugs
+
+## Skill Reference
+
+See `skills/react-testing/SKILL.md` for end-to-end test examples, MSW patterns, and accessibility test scaffolding.

package/skills/frontend/react-native/react-native-expert/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/frontend/react-native/react-native-expert/NOTICE.md

@@ -0,0 +1,11 @@
+# Attribution
+
+This skill is copied from Jeffallan's public `Jeffallan/claude-skills` repository.
+
+- Source: https://github.com/Jeffallan/claude-skills/tree/main/skills/react-native-expert
+- Imported from commit: `e8be415bc94d8d6ebddc2fb50e5d03c6e27d4319`
+- Upstream skill name: `react-native-expert`
+- License: MIT
+- Copyright: Copyright (c) 2025
+
+The upstream MIT license text is preserved in `LICENSE`.

package/skills/frontend/react-native/react-native-expert/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: react-native-expert
+description: Builds, optimizes, and debugs cross-platform mobile applications with React Native and Expo. Implements navigation hierarchies (tabs, stacks, drawers), configures native modules, optimizes FlatList rendering with memo and useCallback, and handles platform-specific code for iOS and Android. Use when building a React Native or Expo mobile app, setting up navigation, integrating native modules, improving scroll performance, handling SafeArea or keyboard input, or configuring Expo SDK projects.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: frontend
+  triggers: React Native, Expo, mobile app, iOS, Android, cross-platform, native module
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: react-expert, flutter-expert, test-master
+---
+
+# React Native Expert
+
+Senior mobile engineer building production-ready cross-platform applications with React Native and Expo.
+
+## Core Workflow
+
+1. **Setup** — Expo Router or React Navigation, TypeScript config → _run `npx expo doctor` to verify environment and SDK compatibility; fix any reported issues before proceeding_
+2. **Structure** — Feature-based organization
+3. **Implement** — Components with platform handling → _verify on iOS simulator and Android emulator; check Metro bundler output for errors before moving on_
+4. **Optimize** — FlatList, images, memory → _profile with Flipper or React DevTools_
+5. **Test** — Both platforms, real devices
+
+### Error Recovery
+- **Metro bundler errors** → clear cache with `npx expo start --clear`, then restart
+- **iOS build fails** → check Xcode logs → resolve native dependency or provisioning issue → rebuild with `npx expo run:ios`
+- **Android build fails** → check `adb logcat` or Gradle output → resolve SDK/NDK version mismatch → rebuild with `npx expo run:android`
+- **Native module not found** → run `npx expo install <module>` to ensure compatible version, then rebuild native layers
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Navigation | `references/expo-router.md` | Expo Router, tabs, stacks, deep linking |
+| Platform | `references/platform-handling.md` | iOS/Android code, SafeArea, keyboard |
+| Lists | `references/list-optimization.md` | FlatList, performance, memo |
+| Storage | `references/storage-hooks.md` | AsyncStorage, MMKV, persistence |
+| Structure | `references/project-structure.md` | Project setup, architecture |
+
+## Constraints
+
+### MUST DO
+- Use FlatList/SectionList for lists (not ScrollView)
+- Implement memo + useCallback for list items
+- Handle SafeAreaView for notches
+- Test on both iOS and Android real devices
+- Use KeyboardAvoidingView for forms
+- Handle Android back button in navigation
+
+### MUST NOT DO
+- Use ScrollView for large lists
+- Use inline styles extensively (creates new objects)
+- Hardcode dimensions (use Dimensions API or flex)
+- Ignore memory leaks from subscriptions
+- Skip platform-specific testing
+- Use waitFor/setTimeout for animations (use Reanimated)
+
+## Code Examples
+
+### Optimized FlatList with memo + useCallback
+
+```tsx
+import React, { memo, useCallback } from 'react';
+import { FlatList, View, Text, StyleSheet } from 'react-native';
+
+type Item = { id: string; title: string };
+
+const ListItem = memo(({ title, onPress }: { title: string; onPress: () => void }) => (
+  <View style={styles.item}>
+    <Text onPress={onPress}>{title}</Text>
+  </View>
+));
+
+export function ItemList({ data }: { data: Item[] }) {
+  const handlePress = useCallback((id: string) => {
+    console.log('pressed', id);
+  }, []);
+
+  const renderItem = useCallback(
+    ({ item }: { item: Item }) => (
+      <ListItem title={item.title} onPress={() => handlePress(item.id)} />
+    ),
+    [handlePress]
+  );
+
+  return (
+    <FlatList
+      data={data}
+      keyExtractor={(item) => item.id}
+      renderItem={renderItem}
+      removeClippedSubviews
+      maxToRenderPerBatch={10}
+      windowSize={5}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  item: { padding: 16, borderBottomWidth: StyleSheet.hairlineWidth },
+});
+```
+
+### KeyboardAvoidingView Form
+
+```tsx
+import React from 'react';
+import {
+  KeyboardAvoidingView,
+  Platform,
+  ScrollView,
+  TextInput,
+  StyleSheet,
+  SafeAreaView,
+} from 'react-native';
+
+export function LoginForm() {
+  return (
+    <SafeAreaView style={styles.safe}>
+      <KeyboardAvoidingView
+        style={styles.flex}
+        behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+      >
+        <ScrollView contentContainerStyle={styles.content} keyboardShouldPersistTaps="handled">
+          <TextInput style={styles.input} placeholder="Email" autoCapitalize="none" />
+          <TextInput style={styles.input} placeholder="Password" secureTextEntry />
+        </ScrollView>
+      </KeyboardAvoidingView>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  safe: { flex: 1 },
+  flex: { flex: 1 },
+  content: { padding: 16, gap: 12 },
+  input: { borderWidth: 1, borderRadius: 8, padding: 12, fontSize: 16 },
+});
+```
+
+### Platform-Specific Component
+
+```tsx
+import { Platform, StyleSheet, View, Text } from 'react-native';
+
+export function StatusChip({ label }: { label: string }) {
+  return (
+    <View style={styles.chip}>
+      <Text style={styles.label}>{label}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  chip: {
+    paddingHorizontal: 12,
+    paddingVertical: 4,
+    borderRadius: 999,
+    backgroundColor: '#0a7ea4',
+    // Platform-specific shadow
+    ...Platform.select({
+      ios: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.2, shadowRadius: 4 },
+      android: { elevation: 3 },
+    }),
+  },
+  label: { color: '#fff', fontSize: 13, fontWeight: '600' },
+});
+```
+
+## Output Format
+
+When implementing React Native features, deliver:
+1. **Component code** — TypeScript, with prop types defined
+2. **Platform handling** — `Platform.select` or `.ios.tsx` / `.android.tsx` splits as needed
+3. **Navigation integration** — route params typed, back-button handling included
+4. **Performance notes** — memo boundaries, key extractor strategy, image caching
+
+## Knowledge Reference
+
+React Native 0.73+, Expo SDK 50+, Expo Router, React Navigation 7, Reanimated 3, Gesture Handler, AsyncStorage, MMKV, React Query, Zustand
+
+[Documentation](https://jeffallan.github.io/claude-skills/skills/frontend/react-native-expert/)

package/skills/frontend/react-native/react-native-expert/references/expo-router.md

@@ -0,0 +1,187 @@
+# Expo Router
+
+## Project Structure
+
+```
+app/
+├── _layout.tsx           # Root layout
+├── index.tsx             # Home (/)
+├── +not-found.tsx        # 404 page
+├── (tabs)/               # Tab group
+│   ├── _layout.tsx       # Tab bar config
+│   ├── index.tsx         # First tab
+│   └── profile.tsx       # Profile tab
+├── (auth)/               # Auth group (no tabs)
+│   ├── _layout.tsx
+│   ├── login.tsx
+│   └── register.tsx
+├── settings/
+│   ├── _layout.tsx       # Stack layout
+│   ├── index.tsx         # Settings main
+│   └── notifications.tsx
+└── details/[id].tsx      # Dynamic route
+```
+
+## Root Layout
+
+```typescript
+// app/_layout.tsx
+import { Stack } from 'expo-router';
+import { ThemeProvider } from '@react-navigation/native';
+
+export default function RootLayout() {
+  return (
+    <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
+      <Stack screenOptions={{ headerShown: false }}>
+        <Stack.Screen name="(tabs)" />
+        <Stack.Screen name="(auth)" />
+        <Stack.Screen
+          name="details/[id]"
+          options={{ presentation: 'modal' }}
+        />
+      </Stack>
+    </ThemeProvider>
+  );
+}
+```
+
+## Tab Layout
+
+```typescript
+// app/(tabs)/_layout.tsx
+import { Tabs } from 'expo-router';
+import { Ionicons } from '@expo/vector-icons';
+
+export default function TabLayout() {
+  return (
+    <Tabs
+      screenOptions={{
+        tabBarActiveTintColor: '#007AFF',
+        headerShown: true,
+      }}
+    >
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: 'Home',
+          tabBarIcon: ({ color, size }) => (
+            <Ionicons name="home" color={color} size={size} />
+          ),
+        }}
+      />
+      <Tabs.Screen
+        name="profile"
+        options={{
+          title: 'Profile',
+          tabBarIcon: ({ color, size }) => (
+            <Ionicons name="person" color={color} size={size} />
+          ),
+        }}
+      />
+    </Tabs>
+  );
+}
+```
+
+## Navigation
+
+```typescript
+import { router, useLocalSearchParams, Link } from 'expo-router';
+
+// Programmatic navigation
+router.push('/details/123');           // Push to stack
+router.replace('/home');               // Replace current
+router.back();                          // Go back
+router.canGoBack();                     // Check if can go back
+
+// With params
+router.push({
+  pathname: '/details/[id]',
+  params: { id: '123', title: 'Item' },
+});
+
+// Link component
+<Link href="/profile" asChild>
+  <Pressable>
+    <Text>Go to Profile</Text>
+  </Pressable>
+</Link>
+
+// Reading params
+function DetailsScreen() {
+  const { id, title } = useLocalSearchParams<{ id: string; title?: string }>();
+  return <Text>Details for {id}</Text>;
+}
+```
+
+## Protected Routes
+
+```typescript
+// app/(auth)/_layout.tsx
+import { Redirect, Stack } from 'expo-router';
+import { useAuth } from '@/hooks/useAuth';
+
+export default function AuthLayout() {
+  const { user, isLoading } = useAuth();
+
+  if (isLoading) {
+    return <LoadingScreen />;
+  }
+
+  if (user) {
+    return <Redirect href="/(tabs)" />;
+  }
+
+  return <Stack screenOptions={{ headerShown: false }} />;
+}
+
+// app/(tabs)/_layout.tsx
+export default function TabLayout() {
+  const { user, isLoading } = useAuth();
+
+  if (isLoading) {
+    return <LoadingScreen />;
+  }
+
+  if (!user) {
+    return <Redirect href="/(auth)/login" />;
+  }
+
+  return <Tabs>...</Tabs>;
+}
+```
+
+## Deep Linking
+
+```json
+// app.json
+{
+  "expo": {
+    "scheme": "myapp",
+    "web": {
+      "bundler": "metro"
+    }
+  }
+}
+```
+
+```typescript
+// Handle: myapp://details/123
+// app/details/[id].tsx handles automatically
+```
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| `<Stack>` | Stack navigator |
+| `<Tabs>` | Tab navigator |
+| `<Drawer>` | Drawer navigator |
+| `<Link>` | Declarative navigation |
+
+| router method | Behavior |
+|---------------|----------|
+| `push()` | Add to stack |
+| `replace()` | Replace current |
+| `back()` | Go back |
+| `dismissAll()` | Dismiss modals |