@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/src/claude/skills/frontend-development/resources/typescript-standards.md

@@ -1,418 +0,0 @@
-# TypeScript Standards
-
-TypeScript best practices for type safety and maintainability in React frontend code.
-
----
-
-## Strict Mode
-
-### Configuration
-
-TypeScript strict mode is **enabled** in the project:
-
-```json
-// tsconfig.json
-{
-    "compilerOptions": {
-        "strict": true,
-        "noImplicitAny": true,
-        "strictNullChecks": true
-    }
-}
-```
-
-**This means:**
-- No implicit `any` types
-- Null/undefined must be handled explicitly
-- Type safety enforced
-
----
-
-## No `any` Type
-
-### The Rule
-
-```typescript
-// ❌ NEVER use any
-function handleData(data: any) {
-    return data.something;
-}
-
-// ✅ Use specific types
-interface MyData {
-    something: string;
-}
-
-function handleData(data: MyData) {
-    return data.something;
-}
-
-// ✅ Or use unknown for truly unknown data
-function handleUnknown(data: unknown) {
-    if (typeof data === 'object' && data !== null && 'something' in data) {
-        return (data as MyData).something;
-    }
-}
-```
-
-**If you truly don't know the type:**
-- Use `unknown` (forces type checking)
-- Use type guards to narrow
-- Document why type is unknown
-
----
-
-## Explicit Return Types
-
-### Function Return Types
-
-```typescript
-// ✅ CORRECT - Explicit return type
-function getUser(id: number): Promise<User> {
-    return apiClient.get(`/users/${id}`);
-}
-
-function calculateTotal(items: Item[]): number {
-    return items.reduce((sum, item) => sum + item.price, 0);
-}
-
-// ❌ AVOID - Implicit return type (less clear)
-function getUser(id: number) {
-    return apiClient.get(`/users/${id}`);
-}
-```
-
-### Component Return Types
-
-```typescript
-// React.FC already provides return type (ReactElement)
-export const MyComponent: React.FC<Props> = ({ prop }) => {
-    return <div>{prop}</div>;
-};
-
-// For custom hooks
-function useMyData(id: number): { data: Data; isLoading: boolean } {
-    const [data, setData] = useState<Data | null>(null);
-    const [isLoading, setIsLoading] = useState(true);
-
-    return { data: data!, isLoading };
-}
-```
-
----
-
-## Type Imports
-
-### Use 'type' Keyword
-
-```typescript
-// ✅ CORRECT - Explicitly mark as type import
-import type { User } from '~types/user';
-import type { Post } from '~types/post';
-import type { SxProps, Theme } from '@mui/material';
-
-// ❌ AVOID - Mixed value and type imports
-import { User } from '~types/user';  // Unclear if type or value
-```
-
-**Benefits:**
-- Clearly separates types from values
-- Better tree-shaking
-- Prevents circular dependencies
-- TypeScript compiler optimization
-
----
-
-## Component Prop Interfaces
-
-### Interface Pattern
-
-```typescript
-/**
- * Props for MyComponent
- */
-interface MyComponentProps {
-    /** The user ID to display */
-    userId: number;
-
-    /** Optional callback when action completes */
-    onComplete?: () => void;
-
-    /** Display mode for the component */
-    mode?: 'view' | 'edit';
-
-    /** Additional CSS classes */
-    className?: string;
-}
-
-export const MyComponent: React.FC<MyComponentProps> = ({
-    userId,
-    onComplete,
-    mode = 'view',  // Default value
-    className,
-}) => {
-    return <div>...</div>;
-};
-```
-
-**Key Points:**
-- Separate interface for props
-- JSDoc comments for each prop
-- Optional props use `?`
-- Provide defaults in destructuring
-
-### Props with Children
-
-```typescript
-interface ContainerProps {
-    children: React.ReactNode;
-    title: string;
-}
-
-// React.FC automatically includes children type, but be explicit
-export const Container: React.FC<ContainerProps> = ({ children, title }) => {
-    return (
-        <div>
-            <h2>{title}</h2>
-            {children}
-        </div>
-    );
-};
-```
-
----
-
-## Utility Types
-
-### Partial<T>
-
-```typescript
-// Make all properties optional
-type UserUpdate = Partial<User>;
-
-function updateUser(id: number, updates: Partial<User>) {
-    // updates can have any subset of User properties
-}
-```
-
-### Pick<T, K>
-
-```typescript
-// Select specific properties
-type UserPreview = Pick<User, 'id' | 'name' | 'email'>;
-
-const preview: UserPreview = {
-    id: 1,
-    name: 'John',
-    email: 'john@example.com',
-    // Other User properties not allowed
-};
-```
-
-### Omit<T, K>
-
-```typescript
-// Exclude specific properties
-type UserWithoutPassword = Omit<User, 'password' | 'passwordHash'>;
-
-const publicUser: UserWithoutPassword = {
-    id: 1,
-    name: 'John',
-    email: 'john@example.com',
-    // password and passwordHash not allowed
-};
-```
-
-### Required<T>
-
-```typescript
-// Make all properties required
-type RequiredConfig = Required<Config>;  // All optional props become required
-```
-
-### Record<K, V>
-
-```typescript
-// Type-safe object/map
-const userMap: Record<string, User> = {
-    'user1': { id: 1, name: 'John' },
-    'user2': { id: 2, name: 'Jane' },
-};
-
-// For styles
-import type { SxProps, Theme } from '@mui/material';
-
-const styles: Record<string, SxProps<Theme>> = {
-    container: { p: 2 },
-    header: { mb: 1 },
-};
-```
-
----
-
-## Type Guards
-
-### Basic Type Guards
-
-```typescript
-function isUser(data: unknown): data is User {
-    return (
-        typeof data === 'object' &&
-        data !== null &&
-        'id' in data &&
-        'name' in data
-    );
-}
-
-// Usage
-if (isUser(response)) {
-    console.log(response.name);  // TypeScript knows it's User
-}
-```
-
-### Discriminated Unions
-
-```typescript
-type LoadingState =
-    | { status: 'idle' }
-    | { status: 'loading' }
-    | { status: 'success'; data: Data }
-    | { status: 'error'; error: Error };
-
-function Component({ state }: { state: LoadingState }) {
-    // TypeScript narrows type based on status
-    if (state.status === 'success') {
-        return <Display data={state.data} />;  // data available here
-    }
-
-    if (state.status === 'error') {
-        return <Error error={state.error} />;  // error available here
-    }
-
-    return <Loading />;
-}
-```
-
----
-
-## Generic Types
-
-### Generic Functions
-
-```typescript
-function getById<T>(items: T[], id: number): T | undefined {
-    return items.find(item => (item as any).id === id);
-}
-
-// Usage with type inference
-const users: User[] = [...];
-const user = getById(users, 123);  // Type: User | undefined
-```
-
-### Generic Components
-
-```typescript
-interface ListProps<T> {
-    items: T[];
-    renderItem: (item: T) => React.ReactNode;
-}
-
-export function List<T>({ items, renderItem }: ListProps<T>): React.ReactElement {
-    return (
-        <div>
-            {items.map((item, index) => (
-                <div key={index}>{renderItem(item)}</div>
-            ))}
-        </div>
-    );
-}
-
-// Usage
-<List<User>
-    items={users}
-    renderItem={(user) => <UserCard user={user} />}
-/>
-```
-
----
-
-## Type Assertions (Use Sparingly)
-
-### When to Use
-
-```typescript
-// ✅ OK - When you know more than TypeScript
-const element = document.getElementById('my-element') as HTMLInputElement;
-const value = element.value;
-
-// ✅ OK - API response that you've validated
-const response = await api.getData();
-const user = response.data as User;  // You know the shape
-```
-
-### When NOT to Use
-
-```typescript
-// ❌ AVOID - Circumventing type safety
-const data = getData() as any;  // WRONG - defeats TypeScript
-
-// ❌ AVOID - Unsafe assertion
-const value = unknownValue as string;  // Might not actually be string
-```
-
----
-
-## Null/Undefined Handling
-
-### Optional Chaining
-
-```typescript
-// ✅ CORRECT
-const name = user?.profile?.name;
-
-// Equivalent to:
-const name = user && user.profile && user.profile.name;
-```
-
-### Nullish Coalescing
-
-```typescript
-// ✅ CORRECT
-const displayName = user?.name ?? 'Anonymous';
-
-// Only uses default if null or undefined
-// (Different from || which triggers on '', 0, false)
-```
-
-### Non-Null Assertion (Use Carefully)
-
-```typescript
-// ✅ OK - When you're certain value exists
-const data = queryClient.getQueryData<Data>(['data'])!;
-
-// ⚠️ CAREFUL - Only use when you KNOW it's not null
-// Better to check explicitly:
-const data = queryClient.getQueryData<Data>(['data']);
-if (data) {
-    // Use data
-}
-```
-
----
-
-## Summary
-
-**TypeScript Checklist:**
-- ✅ Strict mode enabled
-- ✅ No `any` type (use `unknown` if needed)
-- ✅ Explicit return types on functions
-- ✅ Use `import type` for type imports
-- ✅ JSDoc comments on prop interfaces
-- ✅ Utility types (Partial, Pick, Omit, Required, Record)
-- ✅ Type guards for narrowing
-- ✅ Optional chaining and nullish coalescing
-- ❌ Avoid type assertions unless necessary
-
-**See Also:**
-- [component-patterns.md](component-patterns.md) - Component typing
-- [data-fetching.md](data-fetching.md) - API typing

package/src/claude/skills/mobile-development/SKILL.md

@@ -1,218 +0,0 @@
----
-name: hapo:mobile-development
-description: Build mobile apps with React Native, Flutter, Swift/SwiftUI, Kotlin/Jetpack Compose. Use for iOS/Android, mobile UX, performance optimization, offline-first, app store deployment.
-license: MIT
-user-invocable: true
-when_to_use: "Invoke to build or modify mobile app features and UI."
-category: frontend
-keywords: [mobile, app, ios, android]
-argument-hint: "[platform] [feature]"
-metadata:
-  author: haposoft
-  version: "1.0.0"
----
-# Mobile Development Skill
-
-Production-ready mobile development with modern frameworks, best practices, and mobile-first thinking patterns.
-
-## When to Use
-
-- Building mobile applications (iOS, Android, or cross-platform)
-- Implementing mobile-first design and UX patterns
-- Optimizing for mobile constraints (battery, memory, network, small screens)
-- Making native vs cross-platform technology decisions
-- Implementing offline-first architecture and data sync
-- Following platform-specific guidelines (iOS HIG, Material Design)
-- Optimizing mobile app performance and user experience
-- Implementing mobile security and authentication
-- Testing mobile applications (unit, integration, E2E)
-- Deploying to App Store and Google Play
-
-## Technology Selection Guide
-
-**Cross-Platform Frameworks:**
-- **React Native**: JavaScript expertise, web code sharing, mature ecosystem
-- **Flutter**: Performance-critical apps, complex animations, fastest-growing
-
-**Native Development:**
-- **iOS (Swift/SwiftUI)**: Maximum iOS performance, latest features, Apple ecosystem integration
-- **Android (Kotlin/Jetpack Compose)**: Maximum Android performance, Material Design 3, platform optimization
-
-See: `references/mobile-frameworks.md` for detailed framework comparisons
-
-## Mobile Development Mindset
-
-**The 10 Commandments of Mobile Development:**
-
-1. **Performance is Foundation, Not Feature** - Slow load times can drive users away
-2. **Every Kilobyte, Every Millisecond Matters** - Mobile constraints are real
-3. **Offline-First by Default** - Network is unreliable, design for it
-4. **User Context > Developer Environment** - Think real-world usage scenarios
-5. **Platform Awareness Without Platform Lock-In** - Respect platform conventions
-6. **Iterate, Don't Perfect** - Ship, measure, improve cycle is survival
-7. **Security and Accessibility by Design** - Not afterthoughts
-8. **Test on Real Devices** - Simulators lie about performance
-9. **Architecture Scales with Complexity** - Don't over-engineer simple apps
-10. **Continuous Learning is Survival** - Mobile landscape evolves rapidly
-
-See: `references/mobile-mindset.md` for thinking patterns and decision frameworks
-
-## Reference Navigation
-
-**Core Technologies:**
-- `mobile-frameworks.md` - React Native, Flutter, Swift, Kotlin, framework comparison matrices, when to use each
-- `mobile-ios.md` - Swift 6, SwiftUI, iOS architecture patterns, HIG, App Store requirements, platform capabilities
-- `mobile-android.md` - Kotlin, Jetpack Compose, Material Design 3, Play Store, Android-specific features
-
-**Best Practices & Development Mindset:**
-- `mobile-best-practices.md` - Mobile-first design, performance optimization, offline-first architecture, security, testing, accessibility, deployment, analytics
-- `mobile-debugging.md` - Debugging tools, performance profiling, crash analysis, network debugging, platform-specific debugging
-- `mobile-mindset.md` - Thinking patterns, decision frameworks, platform-specific thinking, common pitfalls, debugging strategies
-
-## Key Best Practices (2024-2025)
-
-**Performance Targets:**
-- App launch: <2 seconds; slow launches risk abandonment
-- Memory usage: <100MB for typical screens
-- Network requests: Batch and cache aggressively
-- Battery impact: Respect Doze Mode and background restrictions
-- Animation: 60 FPS (16.67ms per frame)
-
-**Architecture:**
-- MVVM for small-medium apps (clean separation, testable)
-- MVVM + Clean Architecture for large enterprise apps
-- Offline-first with hybrid sync (push + pull)
-- State management: Zustand (React Native), Riverpod 3 (Flutter), StateFlow (Android)
-
-**Security (OWASP Mobile Top 10):**
-- OAuth 2.0 + JWT + Biometrics for authentication
-- Keychain (iOS) / KeyStore (Android) for sensitive data
-- Certificate pinning for network security
-- Never hardcode credentials or API keys
-- Implement proper session management
-
-**Testing Strategy:**
-- Unit tests: meaningful coverage for business logic
-- Integration tests: Critical user flows
-- E2E tests: Detox (React Native), Appium (cross-platform), XCUITest (iOS), Espresso (Android)
-- Real device testing mandatory before release
-
-**Deployment:**
-- Fastlane for automation across platforms
-- Staged rollouts: Internal → Closed → Open → Production
-- Mandatory: iOS 17 SDK (2024), Android 15 API 35 (Aug 2025)
-- CI/CD saves development time
-
-## Quick Decision Matrix
-
-| Need | Choose |
-|------|--------|
-| JavaScript team, web code sharing | React Native |
-| Performance-critical, complex animations | Flutter |
-| Maximum iOS performance, latest features | Swift/SwiftUI native |
-| Maximum Android performance, Material 3 | Kotlin/Compose native |
-| Rapid prototyping | React Native + Expo |
-| Desktop + mobile | Flutter |
-| Enterprise with JavaScript skills | React Native |
-| Startup with limited resources | Flutter or React Native |
-| Gaming or heavy graphics | Native (Swift/Kotlin) or Unity |
-
-## Framework Quick Comparison (2024-2025)
-
-| Criterion | React Native | Flutter | Swift/SwiftUI | Kotlin/Compose |
-|-----------|--------------|---------|---------------|----------------|
-| **Community footprint** | Large | Large | Apple ecosystem | Android ecosystem |
-| **Adoption** | Established | Established | iOS only | Android only |
-| **Performance** | Near-native when profiled | Near-native when profiled | Native baseline | Native baseline |
-| **Dev Speed** | Fast (hot reload) | Very fast (hot reload) | Fast (Xcode Previews) | Fast (Live Edit) |
-| **Learning Curve** | Easy (JavaScript) | Medium (Dart) | Medium (Swift) | Medium (Kotlin) |
-| **UI Paradigm** | Component-based | Widget-based | Declarative | Declarative |
-| **Community** | Huge (npm) | Growing | Apple ecosystem | Android ecosystem |
-| **Best For** | JS teams, web sharing | Performance, animations | iOS-only apps | Android-only apps |
-
-## Implementation Checklist
-
-**Project Setup:**
-- Choose framework → Initialize project → Configure dev environment → Setup version control → Configure CI/CD → Team standards
-
-**Architecture:**
-- Choose pattern (MVVM/Clean) → Setup folders → State management → Navigation → API layer → Error handling → Logging
-
-**Core Features:**
-- Authentication → Data persistence → API integration → Offline sync → Push notifications → Deep linking → Analytics
-
-**UI/UX:**
-- Design system → Platform guidelines → Accessibility → Responsive layouts → Dark mode → Localization → Animations
-
-**Performance:**
-- Image optimization → Lazy loading → Memory profiling → Network optimization → Battery testing → Launch time optimization
-
-**Quality:**
-- Unit tests → Integration tests → E2E tests → Accessibility testing → Performance testing → Security audit
-
-**Security:**
-- Secure storage → Authentication flow → Network security → Input validation → Session management → Encryption
-
-**Deployment:**
-- App icons/splash → Screenshots → Store listings → Privacy policy → TestFlight/Internal testing → Staged rollout → Monitoring
-
-## Platform-Specific Guidelines
-
-**iOS (Human Interface Guidelines):**
-- Native navigation patterns (tab bar, navigation bar)
-- iOS design patterns (pull to refresh, swipe actions)
-- San Francisco font, iOS color system
-- Haptic feedback, 3D Touch/Haptic Touch
-- Respect safe areas and notch
-
-**Android (Material Design 3):**
-- Material navigation (bottom nav, navigation drawer)
-- Floating action buttons, material components
-- Roboto font, Material You dynamic colors
-- Touch feedback (ripple effects)
-- Respect system bars and gestures
-
-## Common Pitfalls to Avoid
-
-1. **Testing only on simulators** - Real devices show true performance
-2. **Ignoring platform conventions** - Users expect platform-specific patterns
-3. **No offline handling** - Network failures will happen
-4. **Poor memory management** - Leads to crashes and poor UX
-5. **Hardcoded credentials** - Security vulnerability
-6. **No accessibility** - Can exclude users
-7. **Premature optimization** - Optimize based on metrics, not assumptions
-8. **Over-engineering** - Start simple, scale as needed
-9. **Skipping real device testing** - Simulators don't show battery/network issues
-10. **Not respecting battery** - Background processing must be justified
-
-## Performance Budgets
-
-**Recommended Targets:**
-- **App size**: <50MB initial download, <200MB total
-- **Launch time**: <2 seconds to interactive
-- **Screen load**: <1 second for cached data
-- **Network request**: <3 seconds for API calls
-- **Memory**: <100MB for typical screens, <200MB peak
-- **Battery**: Minimize drain during active use
-- **Frame rate**: 60 FPS (16.67ms per frame)
-
-## Resources
-
-**Official Documentation:**
-- React Native: https://reactnative.dev/
-- Flutter: https://flutter.dev/
-- iOS HIG: https://developer.apple.com/design/human-interface-guidelines/
-- Material Design: https://m3.material.io/
-- OWASP Mobile: https://owasp.org/www-project-mobile-top-10/
-
-**Tools & Testing:**
-- Detox E2E: https://wix.github.io/Detox/
-- Appium: https://appium.io/
-- Fastlane: https://fastlane.tools/
-- Firebase: https://firebase.google.com/
-
-**Community:**
-- React Native Directory: https://reactnative.directory/
-- Pub.dev (Flutter packages): https://pub.dev/
-- Awesome React Native: https://github.com/jondot/awesome-react-native
-- Awesome Flutter: https://github.com/Solido/awesome-flutter