autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/state-jotai.md

@@ -0,0 +1,346 @@
+# Jotai Skill
+
+## Primitive Atoms
+\`\`\`typescript
+import { atom, useAtom, useAtomValue, useSetAtom } from 'jotai';
+
+// Primitive atom (read-write)
+const countAtom = atom(0);
+const userAtom = atom<User | null>(null);
+const isDarkModeAtom = atom(false);
+
+// Usage in components
+function Counter() {
+  // Read and write
+  const [count, setCount] = useAtom(countAtom);
+
+  // Read only
+  const count = useAtomValue(countAtom);
+
+  // Write only (doesn't subscribe to changes)
+  const setCount = useSetAtom(countAtom);
+
+  return (
+    <div>
+      <span>{count}</span>
+      <button onClick={() => setCount((c) => c + 1)}>+</button>
+      <button onClick={() => setCount(0)}>Reset</button>
+    </div>
+  );
+}
+\`\`\`
+
+## Derived Atoms (Computed Values)
+\`\`\`typescript
+// Read-only derived atom
+const userNameAtom = atom((get) => get(userAtom)?.name ?? 'Guest');
+
+const isLoggedInAtom = atom((get) => !!get(userAtom));
+
+// Derived from multiple atoms
+const totalAtom = atom((get) => {
+  const items = get(cartItemsAtom);
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+});
+
+// Derived with async
+const userPostsAtom = atom(async (get) => {
+  const user = get(userAtom);
+  if (!user) return [];
+
+  const response = await fetch(\`/api/users/\${user.id}/posts\`);
+  return response.json();
+});
+
+// Usage
+function UserPosts() {
+  const posts = useAtomValue(userPostsAtom); // Suspense required
+  return <PostList posts={posts} />;
+}
+\`\`\`
+
+## Writable Derived Atoms
+\`\`\`typescript
+// Read-write derived atom
+const uppercaseNameAtom = atom(
+  // Getter
+  (get) => get(nameAtom).toUpperCase(),
+  // Setter
+  (get, set, newName: string) => {
+    set(nameAtom, newName.toLowerCase());
+  }
+);
+
+// Lens-like pattern (update nested state)
+const userNameAtom = atom(
+  (get) => get(userAtom)?.name ?? '',
+  (get, set, newName: string) => {
+    const user = get(userAtom);
+    if (user) {
+      set(userAtom, { ...user, name: newName });
+    }
+  }
+);
+
+// Action atom (write-only)
+const incrementAtom = atom(null, (get, set) => {
+  set(countAtom, get(countAtom) + 1);
+});
+
+const fetchUserAtom = atom(null, async (get, set, userId: string) => {
+  set(loadingAtom, true);
+  try {
+    const response = await fetch(\`/api/users/\${userId}\`);
+    const user = await response.json();
+    set(userAtom, user);
+  } catch (error) {
+    set(errorAtom, (error as Error).message);
+  } finally {
+    set(loadingAtom, false);
+  }
+});
+
+// Usage
+function UserLoader({ userId }: { userId: string }) {
+  const fetchUser = useSetAtom(fetchUserAtom);
+
+  useEffect(() => {
+    fetchUser(userId);
+  }, [userId, fetchUser]);
+
+  return <UserProfile />;
+}
+\`\`\`
+
+## Atom Families
+\`\`\`typescript
+import { atomFamily } from 'jotai/utils';
+
+// Create atoms dynamically by parameter
+const todoAtomFamily = atomFamily((id: string) =>
+  atom<Todo | null>(null)
+);
+
+const userByIdAtom = atomFamily((userId: string) =>
+  atom(async () => {
+    const response = await fetch(\`/api/users/\${userId}\`);
+    return response.json();
+  })
+);
+
+// Usage
+function TodoItem({ id }: { id: string }) {
+  const [todo, setTodo] = useAtom(todoAtomFamily(id));
+  // ...
+}
+
+function UserCard({ userId }: { userId: string }) {
+  const user = useAtomValue(userByIdAtom(userId));
+  // ...
+}
+
+// With default value
+const settingAtomFamily = atomFamily(
+  (key: string) => atom(localStorage.getItem(key) ?? ''),
+  (a, b) => a === b // Equality check
+);
+\`\`\`
+
+## Persistence
+\`\`\`typescript
+import { atomWithStorage } from 'jotai/utils';
+
+// Auto-sync with localStorage
+const themeAtom = atomWithStorage('theme', 'light');
+const userPrefsAtom = atomWithStorage<UserPrefs>('userPrefs', {
+  notifications: true,
+  language: 'en',
+});
+
+// Custom storage (sessionStorage)
+const sessionAtom = atomWithStorage('session', null, {
+  getItem: (key) => {
+    const value = sessionStorage.getItem(key);
+    return value ? JSON.parse(value) : null;
+  },
+  setItem: (key, value) => {
+    sessionStorage.setItem(key, JSON.stringify(value));
+  },
+  removeItem: (key) => {
+    sessionStorage.removeItem(key);
+  },
+});
+
+// Async storage (e.g., IndexedDB)
+import { createStore, get as idbGet, set as idbSet, del as idbDel } from 'idb-keyval';
+
+const idbStorage = {
+  getItem: async (key: string) => await idbGet(key),
+  setItem: async (key: string, value: unknown) => await idbSet(key, value),
+  removeItem: async (key: string) => await idbDel(key),
+};
+
+const persistedAtom = atomWithStorage('key', defaultValue, idbStorage);
+\`\`\`
+
+## Async Atoms & Suspense
+\`\`\`typescript
+import { atom, useAtomValue } from 'jotai';
+import { Suspense } from 'react';
+import { loadable } from 'jotai/utils';
+
+// Async atom (requires Suspense)
+const userAtom = atom(async () => {
+  const response = await fetch('/api/user');
+  return response.json();
+});
+
+// With Suspense
+function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserProfile />
+    </Suspense>
+  );
+}
+
+function UserProfile() {
+  const user = useAtomValue(userAtom); // Suspends until resolved
+  return <div>{user.name}</div>;
+}
+
+// Without Suspense (using loadable)
+const loadableUserAtom = loadable(userAtom);
+
+function UserProfileNoSuspense() {
+  const userLoadable = useAtomValue(loadableUserAtom);
+
+  if (userLoadable.state === 'loading') return <div>Loading...</div>;
+  if (userLoadable.state === 'hasError') return <div>Error!</div>;
+  return <div>{userLoadable.data.name}</div>;
+}
+
+// Refresh async atom
+import { useAtomRefresher } from 'jotai/utils';
+
+function UserProfile() {
+  const user = useAtomValue(userAtom);
+  const refresh = useAtomRefresher(userAtom);
+
+  return (
+    <div>
+      <span>{user.name}</span>
+      <button onClick={refresh}>Refresh</button>
+    </div>
+  );
+}
+\`\`\`
+
+## Reset & Utils
+\`\`\`typescript
+import { atomWithReset, useResetAtom, RESET } from 'jotai/utils';
+
+// Resettable atom
+const filterAtom = atomWithReset({
+  search: '',
+  category: 'all',
+  sortBy: 'date',
+});
+
+function Filters() {
+  const [filter, setFilter] = useAtom(filterAtom);
+  const resetFilter = useResetAtom(filterAtom);
+
+  return (
+    <div>
+      <input
+        value={filter.search}
+        onChange={(e) => setFilter((f) => ({ ...f, search: e.target.value }))}
+      />
+      <button onClick={resetFilter}>Reset Filters</button>
+      {/* Or: setFilter(RESET) */}
+    </div>
+  );
+}
+
+// Select atom (derived with equality)
+import { selectAtom } from 'jotai/utils';
+
+const userNameAtom = selectAtom(userAtom, (user) => user?.name);
+
+// Focus atom (lens for nested state)
+import { focusAtom } from 'jotai-optics';
+
+const nameAtom = focusAtom(userAtom, (optic) => optic.prop('name'));
+\`\`\`
+
+## Provider & Store
+\`\`\`typescript
+import { Provider, createStore, useStore } from 'jotai';
+
+// Create isolated store
+const myStore = createStore();
+
+// Set initial values
+myStore.set(countAtom, 10);
+myStore.set(userAtom, { id: '1', name: 'John' });
+
+// Get value outside React
+const count = myStore.get(countAtom);
+
+// Subscribe outside React
+const unsubscribe = myStore.sub(countAtom, () => {
+  console.log('Count changed:', myStore.get(countAtom));
+});
+
+// Provide store to React tree
+function App() {
+  return (
+    <Provider store={myStore}>
+      <Counter />
+    </Provider>
+  );
+}
+
+// Access store in component
+function Debug() {
+  const store = useStore();
+  console.log('Store:', store.get(countAtom));
+  return null;
+}
+\`\`\`
+
+## DevTools
+\`\`\`typescript
+import { useAtomsDebugValue } from 'jotai-devtools';
+
+// In development
+function DebugAtoms() {
+  useAtomsDebugValue();
+  return null;
+}
+
+function App() {
+  return (
+    <Provider>
+      {process.env.NODE_ENV === 'development' && <DebugAtoms />}
+      <MainApp />
+    </Provider>
+  );
+}
+\`\`\`
+
+## ❌ DON'T
+- Create atoms inside components (recreates on every render)
+- Forget Suspense for async atoms
+- Use useAtom when you only need read or write
+- Mutate atom values directly
+
+## ✅ DO
+- Define atoms outside components (module level)
+- Use useAtomValue for read-only subscriptions
+- Use useSetAtom when you don't need the value
+- Use atomFamily for dynamic/parameterized atoms
+- Use atomWithStorage for persistence
+- Use loadable for non-Suspense async handling
+- Use derived atoms for computed values

package/.claude/skills/state-mobx.md

@@ -0,0 +1,353 @@
+# MobX Skill
+
+## Basic Store
+\`\`\`typescript
+import { makeAutoObservable, runInAction } from 'mobx';
+
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+class UserStore {
+  // Observable state
+  user: User | null = null;
+  loading = false;
+  error: string | null = null;
+
+  constructor() {
+    // Automatically makes all properties observable,
+    // getters computed, and methods actions
+    makeAutoObservable(this);
+  }
+
+  // Computed value (automatically cached)
+  get isLoggedIn() {
+    return !!this.user;
+  }
+
+  get displayName() {
+    return this.user?.name ?? 'Guest';
+  }
+
+  // Synchronous action
+  setUser(user: User) {
+    this.user = user;
+  }
+
+  logout() {
+    this.user = null;
+    this.error = null;
+  }
+
+  // Async action
+  async login(email: string, password: string) {
+    this.loading = true;
+    this.error = null;
+
+    try {
+      const response = await fetch('/api/auth/login', {
+        method: 'POST',
+        body: JSON.stringify({ email, password }),
+      });
+
+      if (!response.ok) throw new Error('Login failed');
+
+      const user = await response.json();
+
+      // Must wrap state changes after await in runInAction
+      runInAction(() => {
+        this.user = user;
+        this.loading = false;
+      });
+    } catch (error) {
+      runInAction(() => {
+        this.error = (error as Error).message;
+        this.loading = false;
+      });
+    }
+  }
+}
+
+export const userStore = new UserStore();
+\`\`\`
+
+## Manual Observable Configuration
+\`\`\`typescript
+import { makeObservable, observable, computed, action, flow } from 'mobx';
+
+class TodoStore {
+  todos: Todo[] = [];
+  filter: 'all' | 'active' | 'completed' = 'all';
+
+  constructor() {
+    makeObservable(this, {
+      // State
+      todos: observable,
+      filter: observable,
+      // Computed
+      filteredTodos: computed,
+      totalCount: computed,
+      // Actions
+      addTodo: action,
+      toggleTodo: action,
+      removeTodo: action,
+      // Generators (for async)
+      fetchTodos: flow,
+    });
+  }
+
+  get filteredTodos() {
+    switch (this.filter) {
+      case 'active':
+        return this.todos.filter((t) => !t.completed);
+      case 'completed':
+        return this.todos.filter((t) => t.completed);
+      default:
+        return this.todos;
+    }
+  }
+
+  get totalCount() {
+    return this.todos.length;
+  }
+
+  addTodo(text: string) {
+    this.todos.push({
+      id: crypto.randomUUID(),
+      text,
+      completed: false,
+    });
+  }
+
+  toggleTodo(id: string) {
+    const todo = this.todos.find((t) => t.id === id);
+    if (todo) {
+      todo.completed = !todo.completed;
+    }
+  }
+
+  removeTodo(id: string) {
+    this.todos = this.todos.filter((t) => t.id !== id);
+  }
+
+  // Flow for async (alternative to runInAction)
+  *fetchTodos() {
+    this.loading = true;
+    try {
+      const response = yield fetch('/api/todos');
+      const todos = yield response.json();
+      this.todos = todos;
+    } finally {
+      this.loading = false;
+    }
+  }
+}
+\`\`\`
+
+## React Integration
+\`\`\`tsx
+import { observer } from 'mobx-react-lite';
+import { userStore } from './stores/userStore';
+
+// Wrap component with observer to react to observable changes
+const UserProfile = observer(() => {
+  const { user, isLoggedIn, loading, logout } = userStore;
+
+  if (loading) return <div>Loading...</div>;
+
+  if (!isLoggedIn) {
+    return <button onClick={() => userStore.login('test@example.com', 'password')}>Login</button>;
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {user?.name}</h1>
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+});
+
+// With local observable state
+import { useLocalObservable } from 'mobx-react-lite';
+
+const Counter = observer(() => {
+  const state = useLocalObservable(() => ({
+    count: 0,
+    increment() {
+      this.count++;
+    },
+    decrement() {
+      this.count--;
+    },
+    get doubled() {
+      return this.count * 2;
+    },
+  }));
+
+  return (
+    <div>
+      <span>{state.count} (doubled: {state.doubled})</span>
+      <button onClick={state.increment}>+</button>
+      <button onClick={state.decrement}>-</button>
+    </div>
+  );
+});
+\`\`\`
+
+## Context Provider Pattern
+\`\`\`tsx
+import { createContext, useContext } from 'react';
+import { UserStore } from './stores/UserStore';
+import { TodoStore } from './stores/TodoStore';
+
+// Root store combining all stores
+class RootStore {
+  userStore: UserStore;
+  todoStore: TodoStore;
+
+  constructor() {
+    this.userStore = new UserStore(this);
+    this.todoStore = new TodoStore(this);
+  }
+}
+
+const StoreContext = createContext<RootStore | null>(null);
+
+export function StoreProvider({ children }: { children: React.ReactNode }) {
+  const store = new RootStore();
+  return (
+    <StoreContext.Provider value={store}>
+      {children}
+    </StoreContext.Provider>
+  );
+}
+
+export function useStore() {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error('useStore must be used within StoreProvider');
+  return store;
+}
+
+// Usage
+const TodoList = observer(() => {
+  const { todoStore } = useStore();
+  return (
+    <ul>
+      {todoStore.filteredTodos.map((todo) => (
+        <li key={todo.id}>{todo.text}</li>
+      ))}
+    </ul>
+  );
+});
+\`\`\`
+
+## Reactions
+\`\`\`typescript
+import { autorun, reaction, when } from 'mobx';
+
+// autorun - runs immediately and on every change
+const dispose1 = autorun(() => {
+  console.log('User:', userStore.user?.name);
+});
+
+// reaction - only runs when specific data changes
+const dispose2 = reaction(
+  () => userStore.user, // Data function
+  (user, previousUser) => { // Effect function
+    console.log('User changed from', previousUser, 'to', user);
+    if (user) {
+      localStorage.setItem('lastUserId', user.id);
+    }
+  },
+  { fireImmediately: false } // Don't run on setup
+);
+
+// when - runs once when condition is met
+const dispose3 = when(
+  () => userStore.isLoggedIn,
+  () => {
+    console.log('User logged in!');
+    // Fetch user-specific data
+  }
+);
+
+// Cleanup
+dispose1();
+dispose2();
+dispose3();
+
+// In React useEffect
+useEffect(() => {
+  const dispose = autorun(() => {
+    document.title = \`\${todoStore.totalCount} todos\`;
+  });
+
+  return () => dispose();
+}, []);
+\`\`\`
+
+## Persistence
+\`\`\`typescript
+import { makePersistable } from 'mobx-persist-store';
+
+class SettingsStore {
+  theme: 'light' | 'dark' = 'light';
+  language = 'en';
+
+  constructor() {
+    makeAutoObservable(this);
+
+    makePersistable(this, {
+      name: 'SettingsStore',
+      properties: ['theme', 'language'],
+      storage: window.localStorage,
+    });
+  }
+
+  setTheme(theme: 'light' | 'dark') {
+    this.theme = theme;
+  }
+}
+
+// Or manual persistence with reaction
+class UserStore {
+  constructor() {
+    makeAutoObservable(this);
+
+    // Load from storage
+    const stored = localStorage.getItem('user');
+    if (stored) {
+      this.user = JSON.parse(stored);
+    }
+
+    // Save on changes
+    reaction(
+      () => this.user,
+      (user) => {
+        if (user) {
+          localStorage.setItem('user', JSON.stringify(user));
+        } else {
+          localStorage.removeItem('user');
+        }
+      }
+    );
+  }
+}
+\`\`\`
+
+## ❌ DON'T
+- Forget to wrap components with observer
+- Mutate state outside of actions
+- Forget runInAction after await
+- Destructure observables (loses reactivity)
+- Create stores inside components
+
+## ✅ DO
+- Use makeAutoObservable for simple stores
+- Use observer() for all components using observables
+- Use runInAction or flow for async mutations
+- Use reactions for side effects
+- Access store properties directly (not destructured)
+- Create stores once and share via context