@mind-fold/open-flow 0.1.17 → 0.2.2

package/dist/templates/markdown/structure/frontend/state-management.md.txt

@@ -0,0 +1,293 @@
+# State Management
+
+> Local state, server state, and global state patterns
+
+---
+
+## State Types
+
+| Type | When to Use | Tool |
+|------|-------------|------|
+| **Local State** | UI state, form inputs | `useState` |
+| **Server State** | Data from API | React Query |
+| **Global State** | App-wide state, auth | Context / Zustand |
+| **URL State** | Filters, pagination | `useSearchParams` |
+
+---
+
+## Local State
+
+For component-specific UI state.
+
+```typescript
+function Dialog() {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Open</button>
+      {isOpen && <Modal onClose={() => setIsOpen(false)} />}
+    </>
+  );
+}
+```
+
+### Complex Local State
+
+```typescript
+// For related state, use useReducer
+type State = {
+  status: 'idle' | 'loading' | 'success' | 'error';
+  data: User | null;
+  error: string | null;
+};
+
+type Action =
+  | { type: 'loading' }
+  | { type: 'success'; data: User }
+  | { type: 'error'; error: string };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'loading':
+      return { ...state, status: 'loading', error: null };
+    case 'success':
+      return { status: 'success', data: action.data, error: null };
+    case 'error':
+      return { status: 'error', data: null, error: action.error };
+  }
+}
+```
+
+---
+
+## Server State (React Query)
+
+For data fetched from APIs.
+
+### Fetching Data
+
+```typescript
+function UserList() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => api.users.list(),
+    staleTime: 5 * 60 * 1000,  // Consider fresh for 5 minutes
+  });
+  
+  if (isLoading) return <Skeleton />;
+  if (error) return <Error message={error.message} />;
+  
+  return <List items={data} />;
+}
+```
+
+### Mutating Data
+
+```typescript
+function CreateUserForm() {
+  const queryClient = useQueryClient();
+  
+  const createUser = useMutation({
+    mutationFn: api.users.create,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+  });
+  
+  const handleSubmit = (data: CreateUserInput) => {
+    createUser.mutate(data);
+  };
+  
+  return <form onSubmit={handleSubmit}>...</form>;
+}
+```
+
+---
+
+## Global State (Context)
+
+For app-wide state like auth, theme, or locale.
+
+### Auth Context Example
+
+```typescript
+// context/auth-context.tsx
+interface AuthState {
+  user: User | null;
+  isLoading: boolean;
+}
+
+interface AuthContextType extends AuthState {
+  login: (credentials: Credentials) => Promise<void>;
+  logout: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextType | null>(null);
+
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState<AuthState>({
+    user: null,
+    isLoading: true,
+  });
+  
+  useEffect(() => {
+    // Check session on mount
+    checkSession().then(user => {
+      setState({ user, isLoading: false });
+    });
+  }, []);
+  
+  const login = async (credentials: Credentials) => {
+    const user = await api.auth.login(credentials);
+    setState({ user, isLoading: false });
+  };
+  
+  const logout = async () => {
+    await api.auth.logout();
+    setState({ user: null, isLoading: false });
+  };
+  
+  return (
+    <AuthContext.Provider value={{ ...state, login, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within AuthProvider');
+  }
+  return context;
+}
+```
+
+### Usage
+
+```typescript
+function LoginButton() {
+  const { user, login, logout } = useAuth();
+  
+  if (user) {
+    return <button onClick={logout}>Logout</button>;
+  }
+  
+  return <button onClick={() => login(credentials)}>Login</button>;
+}
+```
+
+---
+
+## URL State
+
+For state that should persist in URL (filters, pagination, search).
+
+```typescript
+import { useSearchParams } from 'next/navigation';
+
+function ProductList() {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  
+  // Read from URL
+  const page = Number(searchParams.get('page')) || 1;
+  const category = searchParams.get('category') ?? 'all';
+  
+  // Update URL
+  const setPage = (newPage: number) => {
+    const params = new URLSearchParams(searchParams);
+    params.set('page', String(newPage));
+    router.push(`?${params.toString()}`);
+  };
+  
+  const { data } = useProducts({ page, category });
+  
+  return (
+    <>
+      <CategoryFilter value={category} />
+      <ProductGrid items={data?.items} />
+      <Pagination page={page} onPageChange={setPage} />
+    </>
+  );
+}
+```
+
+---
+
+## State Location Decision Tree
+
+```
+Is the state needed by multiple components?
+├─ No → Local state (useState)
+└─ Yes → Is it from the server?
+         ├─ Yes → React Query
+         └─ No → Should it persist in URL?
+                 ├─ Yes → URL state (searchParams)
+                 └─ No → Context or Zustand
+```
+
+---
+
+## Anti-Patterns
+
+### Don't Sync Server State to Local State
+
+```typescript
+// ❌ BAD: Duplicating server state
+const { data: users } = useUsers();
+const [localUsers, setLocalUsers] = useState<User[]>([]);
+
+useEffect(() => {
+  if (users) setLocalUsers(users);
+}, [users]);
+
+// ✅ GOOD: Use server state directly
+const { data: users } = useUsers();
+// Use users directly, mutate with mutations
+```
+
+### Don't Overuse Global State
+
+```typescript
+// ❌ BAD: Everything in global state
+const { isModalOpen, setModalOpen } = useGlobalStore();
+
+// ✅ GOOD: Local state for local UI
+const [isModalOpen, setIsModalOpen] = useState(false);
+```
+
+### Don't Put Derived State in State
+
+```typescript
+// ❌ BAD: Storing derived value
+const [items, setItems] = useState([]);
+const [filteredItems, setFilteredItems] = useState([]);
+
+useEffect(() => {
+  setFilteredItems(items.filter(i => i.active));
+}, [items]);
+
+// ✅ GOOD: Compute derived value
+const [items, setItems] = useState([]);
+const filteredItems = items.filter(i => i.active);
+// Or useMemo for expensive computations
+```
+
+---
+
+## Summary
+
+| State Type | Tool | When to Use |
+|------------|------|-------------|
+| UI toggles | `useState` | Modal, dropdown, tabs |
+| Form input | `useState` or form library | Input values |
+| API data | React Query | Fetched data |
+| Auth/User | Context | App-wide user state |
+| Theme | Context | App-wide theme |
+| Filters | URL params | Shareable filters |
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/frontend/type-safety.md.txt

@@ -0,0 +1,275 @@
+# Type Safety
+
+> TypeScript patterns and type inference for frontend
+
+---
+
+## Core Principles
+
+1. **Import from API** - Don't redefine backend types
+2. **Infer when possible** - Let TypeScript do the work
+3. **No `any`** - Use `unknown` with type guards
+4. **No assertions** - Avoid `as` and `!`
+
+---
+
+## Import Types from Backend
+
+Never redefine types that exist in your API layer.
+
+```typescript
+// ✅ GOOD: Import from API package
+import type { User, CreateUserInput } from '@/api/types';
+
+function UserForm({ onSubmit }: { onSubmit: (data: CreateUserInput) => void }) {
+  // ...
+}
+
+// ❌ BAD: Redefining types
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+```
+
+### Why?
+
+- Single source of truth
+- Types stay in sync with API
+- Less code to maintain
+- Compile-time errors if API changes
+
+---
+
+## Type Inference
+
+Let TypeScript infer types when it can.
+
+### State
+
+```typescript
+// ✅ GOOD: Inferred type
+const [count, setCount] = useState(0);  // number
+const [name, setName] = useState('');   // string
+const [user, setUser] = useState<User | null>(null);  // explicit when needed
+
+// ❌ BAD: Redundant type annotation
+const [count, setCount] = useState<number>(0);
+```
+
+### Functions
+
+```typescript
+// ✅ GOOD: Inferred return type
+function formatDate(date: Date) {
+  return date.toISOString();  // returns string
+}
+
+// ✅ GOOD: Explicit when complex
+function getUser(id: string): Promise<User | null> {
+  return api.users.get(id);
+}
+```
+
+### Props
+
+```typescript
+// ✅ GOOD: Props interface
+interface ButtonProps {
+  children: React.ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+function Button({ children, onClick, disabled }: ButtonProps) {
+  return <button onClick={onClick} disabled={disabled}>{children}</button>;
+}
+```
+
+---
+
+## Handling Nullable Values
+
+### Null Checks
+
+```typescript
+// ✅ GOOD: Explicit null check
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user } = useUser(userId);
+  
+  if (!user) {
+    return <Skeleton />;
+  }
+  
+  // TypeScript knows user is not null
+  return <div>{user.name}</div>;
+}
+```
+
+### Optional Chaining
+
+```typescript
+// ✅ GOOD: Optional chaining for nested access
+const userName = user?.profile?.name ?? 'Anonymous';
+
+// ❌ BAD: Non-null assertion
+const userName = user!.profile!.name;
+```
+
+### Default Values
+
+```typescript
+// ✅ GOOD: Default values with nullish coalescing
+const displayName = user.nickname ?? user.name ?? 'Unknown';
+const items = response.data ?? [];
+```
+
+---
+
+## Type Guards
+
+Use type guards for runtime type checking.
+
+### Type Predicates
+
+```typescript
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'email' in value
+  );
+}
+
+// Usage
+function handleData(data: unknown) {
+  if (isUser(data)) {
+    // TypeScript knows data is User
+    console.log(data.email);
+  }
+}
+```
+
+### Discriminated Unions
+
+```typescript
+type Result<T> = 
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+function handleResult(result: Result<User>) {
+  if (result.success) {
+    // TypeScript knows result.data exists
+    console.log(result.data.name);
+  } else {
+    // TypeScript knows result.error exists
+    console.error(result.error);
+  }
+}
+```
+
+---
+
+## Component Props
+
+### Extending HTML Elements
+
+```typescript
+import { type ComponentProps } from 'react';
+
+// Extend button props
+interface ButtonProps extends ComponentProps<'button'> {
+  variant?: 'primary' | 'secondary';
+  isLoading?: boolean;
+}
+
+function Button({ variant = 'primary', isLoading, children, ...props }: ButtonProps) {
+  return (
+    <button className={variant} disabled={isLoading} {...props}>
+      {isLoading ? 'Loading...' : children}
+    </button>
+  );
+}
+```
+
+### Polymorphic Components
+
+```typescript
+type AsProp<C extends React.ElementType> = {
+  as?: C;
+};
+
+type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P);
+
+type PolymorphicProps<C extends React.ElementType, Props = {}> = 
+  React.PropsWithChildren<Props & AsProp<C>> &
+  Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>;
+
+// Usage
+function Text<C extends React.ElementType = 'span'>({
+  as,
+  children,
+  ...props
+}: PolymorphicProps<C>) {
+  const Component = as || 'span';
+  return <Component {...props}>{children}</Component>;
+}
+
+// Can render as different elements
+<Text>Span text</Text>
+<Text as="p">Paragraph text</Text>
+<Text as="h1">Heading text</Text>
+```
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| `any` | Disables type checking | Use `unknown` + guards |
+| `as User` | Unsafe cast | Use type guards |
+| `user!.name` | Runtime crash | Null check first |
+| Redefine API types | Type drift | Import from API |
+
+---
+
+## Best Practices
+
+### DO
+
+```typescript
+// Import types from API
+import type { User } from '@/api/types';
+
+// Use type guards
+if (isUser(data)) { ... }
+
+// Handle nullable explicitly
+if (!user) return null;
+
+// Infer when possible
+const [value, setValue] = useState(0);
+```
+
+### DON'T
+
+```typescript
+// Use any
+const data: any = await fetch(...);
+
+// Cast without validation
+const user = data as User;
+
+// Use non-null assertion
+user!.name;
+
+// Redefine API types locally
+interface User { ... }
+```
+
+---
+
+**Language**: All documentation must be written in **English**.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mind-fold/open-flow",
-	"version": "0.1.17",
+	"version": "0.2.2",
 	"description": "AI-assisted development workflow initializer for Cursor, Claude Code and more",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -14,7 +14,7 @@
 	},
 	"scripts": {
 		"build": "tsc && npm run copy-templates",
-		"copy-templates": "cp -r src/templates/commands/*.txt dist/templates/commands/ && cp -r src/templates/scripts/*.txt dist/templates/scripts/ && cp -r src/templates/markdown/*.txt dist/templates/markdown/",
+		"copy-templates": "cp -r src/templates/commands/*.txt dist/templates/commands/ && cp -r src/templates/scripts/*.txt dist/templates/scripts/ && cp -r src/templates/markdown/*.txt dist/templates/markdown/ && cp -r src/templates/markdown/structure dist/templates/markdown/",
 		"dev": "tsc --watch",
 		"start": "node ./dist/cli/index.js",
 		"prepublishOnly": "npm run build"