@vpxa/aikit 0.1.4 → 0.1.6

package/scaffold/general/skills/react/SKILL.md

@@ -0,0 +1,297 @@
+# React
+
+> Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization. Synthesized from react-dev patterns, react-patterns (React 19), and Vercel React best practices.
+
+## When to Use
+
+**MANDATORY** for the Frontend agent on every React task. Also use when:
+- Building React components, hooks, or pages
+- Working with Server Components or Server Actions
+- Optimizing React performance (re-renders, bundle size, data fetching)
+- Reviewing React code for correctness and best practices
+
+## React 19 Quick Reference
+
+| API | Use Case | Key Change |
+|-----|----------|------------|
+| `ref` as prop | Access DOM/component instance | No more `forwardRef` wrapper |
+| `use()` | Read promises/context in render | Replaces `useContext`, enables async |
+| `useActionState` | Form submission state + error | Replaces `useFormState` |
+| `useOptimistic` | Instant UI feedback | Optimistic updates before server confirms |
+| `useTransition` | Non-urgent state updates | `isPending` for loading states |
+| `<form action>` | Server Actions in forms | Direct server function binding |
+| Server Components | Zero-bundle components | Default in App Router, no `"use client"` |
+| Server Actions | Server mutations | `"use server"` functions, form actions |
+
+## Component Patterns
+
+### Extend Native Elements
+```tsx
+type ButtonProps = React.ComponentProps<"button"> & {
+  variant?: "primary" | "secondary" | "ghost";
+  size?: "sm" | "md" | "lg";
+};
+
+function Button({ variant = "primary", size = "md", className, ...props }: ButtonProps) {
+  return <button className={cn(variants[variant], sizes[size], className)} {...props} />;
+}
+```
+
+### Discriminated Union Props
+```tsx
+type ModalProps =
+  | { variant: "alert"; message: string; onConfirm: () => void }
+  | { variant: "form"; children: React.ReactNode; onSubmit: (data: FormData) => void };
+
+function Modal(props: ModalProps) {
+  switch (props.variant) {
+    case "alert": return <AlertModal {...props} />;
+    case "form": return <FormModal {...props} />;
+  }
+}
+```
+
+### Generic Components
+```tsx
+type TableProps<T> = {
+  data: T[];
+  columns: { key: keyof T; header: string; render?: (value: T[keyof T], row: T) => React.ReactNode }[];
+  onRowClick?: (row: T) => void;
+};
+
+function Table<T extends Record<string, unknown>>({ data, columns, onRowClick }: TableProps<T>) {
+  // ...
+}
+```
+
+### Children Typing
+```tsx
+// Specific children
+type Props = { children: React.ReactElement<TabProps>[] };
+
+// Render function children
+type Props = { children: (data: T) => React.ReactNode };
+
+// String only
+type Props = { children: string };
+```
+
+## Ref as Prop (React 19)
+
+```tsx
+// React 19: pass ref directly, no forwardRef needed
+function Input({ ref, ...props }: React.ComponentProps<"input">) {
+  return <input ref={ref} {...props} />;
+}
+
+// Cleanup function (new in React 19)
+function MeasuredDiv({ ref, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      ref={(node) => {
+        if (node) measureElement(node);
+        return () => cleanupMeasurement(); // cleanup on unmount
+      }}
+      {...props}
+    />
+  );
+}
+```
+
+## Server Components & Actions
+
+### Server Component (default — no directive needed)
+```tsx
+// app/users/page.tsx — Server Component (default)
+import { db } from "@/lib/db";
+
+export default async function UsersPage() {
+  const users = await db.query.users.findMany();  // Direct DB access
+  return <UserList users={users} />;  // Pass data to client
+}
+```
+
+### Client Component (explicit opt-in)
+```tsx
+"use client";
+import { useState, useOptimistic, useTransition } from "react";
+
+export function Counter({ initialCount }: { initialCount: number }) {
+  const [count, setCount] = useState(initialCount);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+### Server Action with Form
+```tsx
+// actions.ts
+"use server";
+import { z } from "zod";
+
+const schema = z.object({ name: z.string().min(1), email: z.string().email() });
+
+export async function createUser(_prev: unknown, formData: FormData) {
+  const result = schema.safeParse(Object.fromEntries(formData));
+  if (!result.success) return { error: result.error.flatten().fieldErrors };
+  await db.insert(users).values(result.data);
+  return { success: true };
+}
+```
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { createUser } from "./actions";
+
+export function CreateUserForm() {
+  const [state, action, isPending] = useActionState(createUser, null);
+  return (
+    <form action={action}>
+      <input name="name" required />
+      {state?.error?.name && <p className="text-red-500">{state.error.name}</p>}
+      <input name="email" type="email" required />
+      {state?.error?.email && <p className="text-red-500">{state.error.email}</p>}
+      <button disabled={isPending}>{isPending ? "Creating..." : "Create"}</button>
+    </form>
+  );
+}
+```
+
+### Optimistic Updates
+```tsx
+"use client";
+import { useOptimistic } from "react";
+
+function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (text: string) => Promise<void> }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (state, newTodo: string) => [...state, { id: "temp", text: newTodo, pending: true }]
+  );
+
+  async function handleAdd(formData: FormData) {
+    const text = formData.get("text") as string;
+    addOptimistic(text);
+    await addTodo(text);
+  }
+
+  return (
+    <form action={handleAdd}>
+      <input name="text" />
+      <button type="submit">Add</button>
+      <ul>
+        {optimisticTodos.map(t => (
+          <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.text}</li>
+        ))}
+      </ul>
+    </form>
+  );
+}
+```
+
+## Event Handler Types
+
+```tsx
+// Always use specific event types
+onClick:    (e: React.MouseEvent<HTMLButtonElement>) => void
+onChange:   (e: React.ChangeEvent<HTMLInputElement>) => void
+onSubmit:   (e: React.FormEvent<HTMLFormElement>) => void
+onKeyDown:  (e: React.KeyboardEvent<HTMLInputElement>) => void
+onFocus:    (e: React.FocusEvent<HTMLInputElement>) => void
+onDrag:     (e: React.DragEvent<HTMLDivElement>) => void
+```
+
+## Hooks Typing
+
+```tsx
+// useState with union
+const [status, setStatus] = useState<"idle" | "loading" | "error">("idle");
+
+// useRef for DOM — pass null, get RefObject
+const inputRef = useRef<HTMLInputElement>(null);
+
+// useRef for mutable value — no null, get MutableRefObject
+const intervalRef = useRef<number>(0);
+
+// useReducer with discriminated actions
+type Action = { type: "increment" } | { type: "set"; payload: number };
+const [count, dispatch] = useReducer((state: number, action: Action) => {
+  switch (action.type) {
+    case "increment": return state + 1;
+    case "set": return action.payload;
+  }
+}, 0);
+
+// Custom hook: return as const for tuple types
+function useToggle(initial = false) {
+  const [value, setValue] = useState(initial);
+  const toggle = useCallback(() => setValue(v => !v), []);
+  return [value, toggle] as const;
+}
+
+// useContext with null guard
+const ctx = useContext(ThemeContext);
+if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
+```
+
+## Performance Rules
+
+### Prevent Async Waterfalls
+```tsx
+// BAD — sequential fetching
+const user = await getUser(id);
+const posts = await getPosts(user.id);  // Waits for user first
+const comments = await getComments(posts[0].id);  // Waits for posts
+
+// GOOD — parallel where possible
+const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
+```
+
+### Bundle Size
+- `dynamic(() => import("./HeavyComponent"))` — lazy load below-fold components
+- Tree-shake: use named exports, avoid `import *`
+- Analyze bundle: `@next/bundle-analyzer` to find bloat
+- Code-split by route — each page loads only its own JS
+- Avoid importing entire libraries: `import { debounce } from "lodash-es"` not `import _ from "lodash"`
+
+### Server-Side Performance
+- Default to Server Components — zero JS shipped to client
+- Stream with Suspense: wrap slow data fetchers in `<Suspense fallback={<Skeleton />}>`
+- Cache expensive computations with `"use cache"` directive
+- Avoid serializing large objects across server/client boundary
+
+### Client-Side Data Fetching
+- Use SWR or React Query — automatic caching, revalidation, error retry
+- Stale-while-revalidate: show cached data instantly, refresh in background
+- Error boundaries: `<ErrorBoundary>` wrapping data-dependent trees
+- Prefetch on hover/viewport for likely next navigations
+
+### Re-render Optimization
+- React Compiler (React 19): auto-memoizes — try this first before manual `useMemo`/`useCallback`
+- If no compiler: `useMemo` for expensive computations, `useCallback` for stable function references
+- Extract static JSX outside components — constants don't re-create
+- Split context: separate frequently-changing state from rarely-changing state
+- `React.memo()` on components receiving only primitive props
+
+### Rendering Performance
+- **Virtualize** lists > 100 items: `@tanstack/react-virtual`, `react-window`
+- Defer heavy computations with `useDeferredValue`
+- Batch state updates (React 18+ does this automatically in event handlers)
+- Avoid reading DOM layout during renders (force sync layout = jank)
+
+### Advanced Patterns
+- Progressive hydration: load and hydrate components as they enter viewport
+- Concurrent features: `useTransition` for non-blocking state updates
+- Suspense caching: combine `<Suspense>` with data cache for instant page transitions
+- React Compiler adoption: enable gradually, check for unsafe patterns first
+
+## Decision Flow
+
+When implementing a React feature:
+
+1. **Server or Client?** → If it uses browser APIs, event handlers, or useState → Client. Everything else → Server.
+2. **Data fetching?** → Server Component for initial data. SWR/React Query for client-side mutations.
+3. **Form?** → Server Action + `useActionState` + Zod validation.
+4. **Optimistic?** → `useOptimistic` for instant feedback.
+5. **Loading?** → `<Suspense>` with skeleton fallback.
+6. **Performance?** → Try React Compiler first. Then manual memo. Then virtualization. Then code splitting.
+7. **Error?** → Error boundaries for rendering errors. try/catch for Server Actions.

package/scaffold/general/skills/typescript/SKILL.md

@@ -0,0 +1,393 @@
+# TypeScript
+
+> Comprehensive TypeScript development patterns — type system performance, compiler configuration, advanced types, type safety, async patterns, module organization, and runtime optimization. Synthesized from pproenca TypeScript rules, TypeScript 6.0 features, wshobson advanced types and modern JS patterns, and Jeffallan typescript-pro patterns.
+
+## When to Use
+
+**MANDATORY** for the Implementer agent on every TypeScript task. Also use when:
+- Writing or reviewing TypeScript code
+- Configuring `tsconfig.json` or compiler options
+- Designing type-safe APIs, libraries, or utilities
+- Optimizing type-check performance or build times
+
+## Type System Performance
+
+These rules prevent slow type-checking and IDE lag:
+
+### Prefer Flat Unions Over Deep Conditionals
+```tsx
+// BAD — O(n²) type checking with deep conditionals
+type DeepResolve<T> = T extends Promise<infer U> ? DeepResolve<U> : T extends Array<infer V> ? DeepResolve<V>[] : T;
+
+// GOOD — flat unions check in O(n)
+type Status = "idle" | "loading" | "success" | "error";
+type Result = SuccessResult | ErrorResult | PendingResult;
+```
+
+### Interface Extends Over Intersection
+```tsx
+// BAD — intersection types are expensive to compute
+type Extended = BaseType & { extra: string } & { more: number };
+
+// GOOD — interface extends is cached by the compiler
+interface Extended extends BaseType {
+  extra: string;
+  more: number;
+}
+```
+
+### Rules
+- **Avoid recursive conditional types** deeper than 3 levels — use iterative mapped types instead
+- **Minimize computed types** in hot paths (function parameters, return types used in many places)
+- **Use `interface` for object shapes**, `type` for unions, intersections, and mapped types
+- **Annotate complex return types** explicitly — don't force the compiler to infer through 5 layers
+- **Avoid generic defaults that trigger deep inference** — provide explicit type arguments at call sites
+- **Break circular type references** — extract shared shapes into separate interfaces
+
+## Compiler Configuration
+
+### Strict Mode (all projects)
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,                    // Enables ALL strict checks
+    "noUncheckedIndexedAccess": true,  // arr[0] is T | undefined
+    "exactOptionalProperties": true,   // undefined ≠ missing
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,           // Required for most bundlers
+    "verbatimModuleSyntax": true       // Explicit import/export type
+  }
+}
+```
+
+### Build Performance
+```jsonc
+{
+  "compilerOptions": {
+    "incremental": true,               // Cache type-check results
+    "tsBuildInfoFile": ".tsbuildinfo",
+    "skipLibCheck": true               // Skip .d.ts checking (safe for apps)
+  }
+}
+```
+
+### Project References (monorepos)
+```jsonc
+// tsconfig.json (root)
+{
+  "references": [
+    { "path": "packages/core" },
+    { "path": "packages/server" },
+    { "path": "packages/cli" }
+  ]
+}
+
+// packages/core/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}
+```
+
+### TypeScript 6.0+ Features
+- **`#/` subpath imports**: `import { utils } from "#/lib/utils"` — no more `../../../` relative paths. Configure in `package.json` `"imports"` field.
+- **`es2025` target**: Set, Iterator, Promise.withResolvers, RegExp v flag
+- **`--noCheck`**: Skip type-checking in CI (when pre-checked) for faster builds
+- **`--stableTypeOrdering`**: Deterministic declaration output for reproducible builds
+- **`isolatedDeclarations`**: Generate `.d.ts` without type-checking — enables parallel builds
+
+## Advanced Types
+
+### Constrained Generics
+```tsx
+// Constrain to ensure property exists
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Constrain with interface
+function merge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
+  return { ...target, ...source };
+}
+```
+
+### Conditional Types
+```tsx
+// Extract return type from async function
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+
+// Distributive conditional
+type NonNullableDeep<T> = T extends null | undefined ? never : T extends object ? { [K in keyof T]: NonNullableDeep<T[K]> } : T;
+
+// Infer from function
+type Parameters<T> = T extends (...args: infer P) => unknown ? P : never;
+```
+
+### Mapped Types
+```tsx
+// Make all properties optional recursively
+type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] };
+
+// Remove readonly
+type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+
+// Key remapping
+type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };
+```
+
+### Template Literal Types
+```tsx
+// Event name typing
+type EventName<T extends string> = `on${Capitalize<T>}`;
+type Events = EventName<"click" | "focus" | "blur">; // "onClick" | "onFocus" | "onBlur"
+
+// Route parameter extraction
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractParams<Rest>
+    : T extends `${string}:${infer Param}`
+      ? Param
+      : never;
+type Params = ExtractParams<"/users/:id/posts/:postId">; // "id" | "postId"
+```
+
+### Utility Type Patterns
+```tsx
+// Deep readonly
+type DeepReadonly<T> = { readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P] };
+
+// Make specific keys required
+type RequireKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;
+
+// Object paths as union
+type Paths<T, D extends number = 3> = [D] extends [never]
+  ? never
+  : T extends object
+    ? { [K in keyof T]-?: K extends string ? `${K}` | `${K}.${Paths<T[K]>}` : never }[keyof T]
+    : never;
+```
+
+## Type Safety Patterns
+
+### Branded Types
+```tsx
+// Prevent mixing IDs of different entities
+type UserId = string & { readonly __brand: "UserId" };
+type OrderId = string & { readonly __brand: "OrderId" };
+
+function createUserId(id: string): UserId { return id as UserId; }
+function createOrderId(id: string): OrderId { return id as OrderId; }
+
+function getUser(id: UserId) { /* ... */ }
+getUser(createOrderId("123")); // TS Error! OrderId is not UserId
+```
+
+### Discriminated Unions with Exhaustive Matching
+```tsx
+type Shape =
+  | { kind: "circle"; radius: number }
+  | { kind: "rect"; width: number; height: number }
+  | { kind: "triangle"; base: number; height: number };
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case "circle": return Math.PI * shape.radius ** 2;
+    case "rect": return shape.width * shape.height;
+    case "triangle": return 0.5 * shape.base * shape.height;
+    default: {
+      const _exhaustive: never = shape;  // Compile error if case missed
+      return _exhaustive;
+    }
+  }
+}
+```
+
+### Result Pattern
+```tsx
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function ok<T>(value: T): Result<T, never> { return { ok: true, value }; }
+function err<E>(error: E): Result<never, E> { return { ok: false, error }; }
+
+async function parseConfig(path: string): Promise<Result<Config, ParseError>> {
+  try {
+    const raw = await readFile(path, "utf-8");
+    return ok(JSON.parse(raw));
+  } catch (e) {
+    return err(new ParseError(`Failed to parse ${path}`, { cause: e }));
+  }
+}
+
+// Usage — forces error handling
+const result = await parseConfig("config.json");
+if (!result.ok) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+const config = result.value;  // Type-narrowed to Config
+```
+
+## Async Patterns
+
+### Parallel Execution
+```tsx
+// Promise.all — fail-fast on first rejection
+const [users, posts] = await Promise.all([getUsers(), getPosts()]);
+
+// Promise.allSettled — get all results regardless of failures
+const results = await Promise.allSettled([getUsers(), getPosts(), getComments()]);
+for (const r of results) {
+  if (r.status === "fulfilled") process(r.value);
+  else logError(r.reason);
+}
+```
+
+### AbortController
+```tsx
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+```
+
+### Async Iterators
+```tsx
+async function* paginate<T>(fetcher: (page: number) => Promise<T[]>): AsyncGenerator<T> {
+  let page = 0;
+  while (true) {
+    const items = await fetcher(page++);
+    if (items.length === 0) break;
+    yield* items;
+  }
+}
+
+// Usage
+for await (const user of paginate(fetchUsersPage)) {
+  processUser(user);
+}
+```
+
+## Module Organization
+
+### Barrel File Performance
+```tsx
+// BAD — barrel files cause entire module tree to load
+// index.ts
+export * from "./userService";
+export * from "./orderService";
+export * from "./paymentService";
+
+// GOOD — direct imports skip barrel overhead
+import { UserService } from "./services/userService";
+```
+
+### Type-Only Imports
+```tsx
+// Always use type-only imports for types
+import type { User, CreateUserDto } from "./types";
+import { UserService } from "./userService";
+// With verbatimModuleSyntax, this is enforced
+```
+
+### Re-export Patterns
+```tsx
+// Public API surface — explicit re-exports
+export { UserService } from "./userService";
+export type { User, CreateUserDto } from "./types";
+// Don't export internal implementation details
+```
+
+## Memory & Runtime
+
+### WeakRef for Caches
+```tsx
+class WeakCache<K extends object, V> {
+  private cache = new Map<K, WeakRef<V & object>>();
+  private registry = new FinalizationRegistry<K>(key => this.cache.delete(key));
+
+  set(key: K, value: V & object): void {
+    this.cache.set(key, new WeakRef(value));
+    this.registry.register(value, key);
+  }
+
+  get(key: K): V | undefined {
+    return this.cache.get(key)?.deref();
+  }
+}
+```
+
+### Efficient Data Structures
+```tsx
+// Use Map/Set for frequent lookups
+const userIndex = new Map<string, User>();       // O(1) lookup
+const activeIds = new Set<string>();              // O(1) has/add/delete
+
+// NOT plain objects for dynamic keys
+const userIndex: Record<string, User> = {};      // Slower for frequent mutations
+```
+
+### Runtime Rules
+- Minimize `Reflect.metadata` and decorator reflection — adds runtime overhead
+- Prefer `structuredClone()` over `JSON.parse(JSON.stringify())` for deep cloning
+- Use `Object.freeze()` for truly immutable constants
+- Avoid `eval()`, `new Function()`, and dynamic `require()` — security + performance issues
+
+## Modern JavaScript Patterns
+
+### Nullish Handling
+```tsx
+const port = config.port ?? 3000;          // Only for null/undefined
+const name = user?.profile?.displayName;   // Optional chaining
+const normalized = (input ??= defaultValue); // Nullish assignment
+```
+
+### Immutable Updates
+```tsx
+// Object spread for shallow updates
+const updated = { ...user, name: "New Name" };
+
+// structuredClone for deep copy
+const deep = structuredClone(complexObject);
+
+// Array immutable operations
+const added = [...items, newItem];
+const removed = items.filter(i => i.id !== targetId);
+const updated = items.map(i => i.id === targetId ? { ...i, ...changes } : i);
+```
+
+### Pipe Pattern
+```tsx
+function pipe<T>(value: T, ...fns: Array<(v: unknown) => unknown>): unknown {
+  return fns.reduce((acc, fn) => fn(acc), value as unknown);
+}
+
+// Usage
+const result = pipe(
+  rawData,
+  validate,
+  normalize,
+  transform,
+  serialize
+);
+```
+
+## Decision Flow
+
+When writing TypeScript:
+
+1. **Interface or Type?** → Object shape = interface. Union/intersection/mapped = type.
+2. **Generic needed?** → If the function works with multiple types and you need to preserve the type → yes. Otherwise keep it simple.
+3. **Strict enough?** → Enable all strict flags. Use branded types for domain IDs. Use discriminated unions for variants.
+4. **Performance?** → Check: Are there deep conditional types? Circular references? Massive unions? Simplify if so.
+5. **Import style?** → `import type` for types. Direct imports, not barrel files. Named exports, not default.
+6. **Error handling?** → Result pattern for expected errors. throw for unexpected/programmer errors.
+7. **Async?** → Promise.all for parallel. AbortController for timeouts. AsyncGenerator for streams.