@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/nextjs/next-cache-components/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: next-cache-components
+description: Next.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag
+---
+
+# Cache Components (Next.js 16+)
+
+Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.
+
+## Enable Cache Components
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+}
+
+export default nextConfig
+```
+
+This replaces the old `experimental.ppr` flag.
+
+---
+
+## Three Content Types
+
+With Cache Components enabled, content falls into three categories:
+
+### 1. Static (Auto-Prerendered)
+
+Synchronous code, imports, pure computations - prerendered at build time:
+
+```tsx
+export default function Page() {
+  return (
+    <header>
+      <h1>Our Blog</h1>  {/* Static - instant */}
+      <nav>...</nav>
+    </header>
+  )
+}
+```
+
+### 2. Cached (`use cache`)
+
+Async data that doesn't need fresh fetches every request:
+
+```tsx
+async function BlogPosts() {
+  'use cache'
+  cacheLife('hours')
+
+  const posts = await db.posts.findMany()
+  return <PostList posts={posts} />
+}
+```
+
+### 3. Dynamic (Suspense)
+
+Runtime data that must be fresh - wrap in Suspense:
+
+```tsx
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <>
+      <BlogPosts />  {/* Cached */}
+
+      <Suspense fallback={<p>Loading...</p>}>
+        <UserPreferences />  {/* Dynamic - streams in */}
+      </Suspense>
+    </>
+  )
+}
+
+async function UserPreferences() {
+  const theme = (await cookies()).get('theme')?.value
+  return <p>Theme: {theme}</p>
+}
+```
+
+---
+
+## `use cache` Directive
+
+### File Level
+
+```tsx
+'use cache'
+
+export default async function Page() {
+  // Entire page is cached
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Component Level
+
+```tsx
+export async function CachedComponent() {
+  'use cache'
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Function Level
+
+```tsx
+export async function getData() {
+  'use cache'
+  return db.query('SELECT * FROM posts')
+}
+```
+
+---
+
+## Cache Profiles
+
+### Built-in Profiles
+
+```tsx
+'use cache'                    // Default: 5m stale, 15m revalidate
+```
+
+```tsx
+'use cache: remote'           // Platform-provided cache (Redis, KV)
+```
+
+```tsx
+'use cache: private'          // For compliance, allows runtime APIs
+```
+
+### `cacheLife()` - Custom Lifetime
+
+```tsx
+import { cacheLife } from 'next/cache'
+
+async function getData() {
+  'use cache'
+  cacheLife('hours')  // Built-in profile
+  return fetch('/api/data')
+}
+```
+
+Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`
+
+### Inline Configuration
+
+```tsx
+async function getData() {
+  'use cache'
+  cacheLife({
+    stale: 3600,      // 1 hour - serve stale while revalidating
+    revalidate: 7200, // 2 hours - background revalidation interval
+    expire: 86400,    // 1 day - hard expiration
+  })
+  return fetch('/api/data')
+}
+```
+
+---
+
+## Cache Invalidation
+
+### `cacheTag()` - Tag Cached Content
+
+```tsx
+import { cacheTag } from 'next/cache'
+
+async function getProducts() {
+  'use cache'
+  cacheTag('products')
+  return db.products.findMany()
+}
+
+async function getProduct(id: string) {
+  'use cache'
+  cacheTag('products', `product-${id}`)
+  return db.products.findUnique({ where: { id } })
+}
+```
+
+### `updateTag()` - Immediate Invalidation
+
+Use when you need the cache refreshed within the same request:
+
+```tsx
+'use server'
+
+import { updateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: FormData) {
+  await db.products.update({ where: { id }, data })
+  updateTag(`product-${id}`)  // Immediate - same request sees fresh data
+}
+```
+
+### `revalidateTag()` - Background Revalidation
+
+Use for stale-while-revalidate behavior:
+
+```tsx
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function createPost(data: FormData) {
+  await db.posts.create({ data })
+  revalidateTag('posts')  // Background - next request sees fresh data
+}
+```
+
+---
+
+## Runtime Data Constraint
+
+**Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`.
+
+### Solution: Pass as Arguments
+
+```tsx
+// Wrong - runtime API inside use cache
+async function CachedProfile() {
+  'use cache'
+  const session = (await cookies()).get('session')?.value  // Error!
+  return <div>{session}</div>
+}
+
+// Correct - extract outside, pass as argument
+async function ProfilePage() {
+  const session = (await cookies()).get('session')?.value
+  return <CachedProfile sessionId={session} />
+}
+
+async function CachedProfile({ sessionId }: { sessionId: string }) {
+  'use cache'
+  // sessionId becomes part of cache key automatically
+  const data = await fetchUserData(sessionId)
+  return <div>{data.name}</div>
+}
+```
+
+### Exception: `use cache: private`
+
+For compliance requirements when you can't refactor:
+
+```tsx
+async function getData() {
+  'use cache: private'
+  const session = (await cookies()).get('session')?.value  // Allowed
+  return fetchData(session)
+}
+```
+
+---
+
+## Cache Key Generation
+
+Cache keys are automatic based on:
+- **Build ID** - invalidates all caches on deploy
+- **Function ID** - hash of function location
+- **Serializable arguments** - props become part of key
+- **Closure variables** - outer scope values included
+
+```tsx
+async function Component({ userId }: { userId: string }) {
+  const getData = async (filter: string) => {
+    'use cache'
+    // Cache key = userId (closure) + filter (argument)
+    return fetch(`/api/users/${userId}?filter=${filter}`)
+  }
+  return getData('active')
+}
+```
+
+---
+
+## Complete Example
+
+```tsx
+import { Suspense } from 'react'
+import { cookies } from 'next/headers'
+import { cacheLife, cacheTag } from 'next/cache'
+
+export default function DashboardPage() {
+  return (
+    <>
+      {/* Static shell - instant from CDN */}
+      <header><h1>Dashboard</h1></header>
+      <nav>...</nav>
+
+      {/* Cached - fast, revalidates hourly */}
+      <Stats />
+
+      {/* Dynamic - streams in with fresh data */}
+      <Suspense fallback={<NotificationsSkeleton />}>
+        <Notifications />
+      </Suspense>
+    </>
+  )
+}
+
+async function Stats() {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('dashboard-stats')
+
+  const stats = await db.stats.aggregate()
+  return <StatsDisplay stats={stats} />
+}
+
+async function Notifications() {
+  const userId = (await cookies()).get('userId')?.value
+  const notifications = await db.notifications.findMany({
+    where: { userId, read: false }
+  })
+  return <NotificationList items={notifications} />
+}
+```
+
+---
+
+## Migration from Previous Versions
+
+| Old Config | Replacement |
+|-----------|-------------|
+| `experimental.ppr` | `cacheComponents: true` |
+| `dynamic = 'force-dynamic'` | Remove (default behavior) |
+| `dynamic = 'force-static'` | `'use cache'` + `cacheLife('max')` |
+| `revalidate = N` | `cacheLife({ revalidate: N })` |
+| `unstable_cache()` | `'use cache'` directive |
+
+---
+
+## Limitations
+
+- **Edge runtime not supported** - requires Node.js
+- **Static export not supported** - needs server
+- **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache`
+
+For request-time randomness outside cache:
+
+```tsx
+import { connection } from 'next/server'
+
+async function DynamicContent() {
+  await connection()  // Defer to request time
+  const id = crypto.randomUUID()  // Different per request
+  return <div>{id}</div>
+}
+```
+
+Sources:
+- [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components)
+- [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)

package/dist/skills/frameworks/react/async-react-patterns/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: async-react-patterns
+description: Guides React 19 async UI state modeling with Actions, useActionState, useTransition, useOptimistic, use, Suspense, Activity, and useEffectEvent. Use when implementing or reviewing React async flows that risk outdated manual data/loading/error state, ad hoc form submission state, useEffect fetching, stale effect callbacks, or hand-rolled optimistic updates. Do not use for async waterfall performance fixes.
+---
+
+# Async React Patterns
+
+Use this skill to avoid outdated async React patterns. Do not use it to fix async waterfalls; use `vercel-react-best-practices` for waterfall and performance work. This skill is about choosing the React 19 primitive that owns pending, optimistic, error, and streaming state instead of hand-rolling those states with scattered `useState`/`useEffect` logic.
+
+## Quick Start
+
+1. Classify the async work:
+   - read data: render under `Suspense`, resolve with `await` in Server Components or `use(promise)` in Client Components
+   - mutate data: model pending/error/settled state as an Action, usually through `<form action>`, `useActionState`, or `startTransition`
+   - preserve hidden UI: use `<Activity>` for stateful hidden sections that should pre-render or resume cheaply
+   - effect callback with latest props: use `useEffectEvent`, not disabled dependencies
+2. Pick the smallest primitive:
+   - form submit -> `<form action={action}>`, `useActionState`, `useFormStatus`
+   - non-form async update -> `useTransition`
+   - instant feedback during mutation/navigation -> `useOptimistic`
+   - stable promise from server/framework -> `use(promise)` inside `Suspense`
+   - RSC cache lifetime cleanup -> `cacheSignal`
+3. Verify UX states: pending indicator, optimistic rollback/settle behavior, error boundary or returned error state, accessibility (`aria-busy`, disabled only when useful).
+
+## Patterns
+
+### Actions For Mutations
+
+- Name async mutation callbacks with `Action` suffix when they are intended to run in a transition or form action.
+- Prefer `<form action>`/`useActionState` for form submissions; React handles pending state, error result state, and uncontrolled form reset.
+- Use `useFormStatus` inside reusable form controls that need the nearest parent form pending state without prop drilling.
+- Use `useTransition` for non-form work such as router/search-param changes, list filtering, tabs, or button-triggered async mutations.
+- Keep urgent input updates outside transitions; put expensive or async follow-up work inside the Action.
+- If setting state after `await` inside `startTransition`, re-check current React docs. React currently documents wrapping post-`await` state updates in another `startTransition`.
+
+### Optimistic UI
+
+- Call `useOptimistic(value, reducer?)` at component top level.
+- Call the optimistic setter only inside an Action, event handler, effect, or callback; never during render.
+- Keep reducers pure. Use a reducer when multiple optimistic operations can overlap or when list updates need typed operations.
+- Let parents own optimistic state when reusable children cannot derive the final display value. Children may expose `setValueAction`, `submitAction`, or `onChangeAction` props for parent-specific logic.
+- Always define the settle path: successful server/router value replaces optimistic value; rejected work rolls back via React or explicit error recovery.
+
+### Reading Async Data
+
+- In Server Components, prefer `async`/`await` when the component can block at that point.
+- To avoid blocking a Server Component shell, create/pass a stable promise to a Client Component and resolve it with `use(promise)` under `Suspense`.
+- Do not create promises during Client Component render for `use`; promises should come from a Suspense-aware framework/library or from the server.
+- Pair `use(promise)` with `Suspense` for loading and an Error Boundary or `promise.catch` fallback for rejection. Do not wrap `use` in `try/catch`.
+- Keep data passed from Server to Client serializable.
+
+### Effects And Background UI
+
+- Do not default to `useEffect` + `fetch` for primary data reads. Prefer framework data loading, Server Components, cached promises, or Suspense-compatible libraries.
+- Use `useEffectEvent` only for callbacks that are conceptually events fired from an Effect and need latest props/state without resubscribing the Effect.
+- Do not put Effect Events in dependency arrays; keep them declared in the same component or Hook as their Effect.
+- Use `<Activity mode="hidden">` for UI likely to be revisited or preloaded while hidden; remember hidden Activities unmount effects and defer hidden updates.
+- Use `cacheSignal` only in React Server Components to abort/cleanup work tied to `cache()` lifetime.
+
+## Review Checklist
+
+- No manual `isLoading`/`error`/`data` state machine where an Action, `useActionState`, `useFormStatus`, `Suspense`, or Error Boundary should own the state.
+- Mutations expose pending, error, optimistic, and settle behavior in one obvious Action path.
+- Reusable components accept Action props instead of owning application-specific async side effects.
+- Suspense boundaries are close enough to avoid blanking the whole page but high enough to prevent boundary soup.
+- Client promises used with `use` are stable, cached, and rejected through Error Boundaries or fallback values.
+- Accessibility reflects async state without over-disabling controls.
+- Experimental or canary APIs from articles are verified against current React docs before use.
+
+## Sources
+
+- React 19 overview: https://react.dev/blog/2024/12/05/react-19
+- React 19.2 overview: https://react.dev/blog/2025/10/01/react-19-2
+- `useOptimistic`: https://react.dev/reference/react/useOptimistic
+- `useTransition`: https://react.dev/reference/react/useTransition
+- `use`: https://react.dev/reference/react/use
+- Async shift article: https://blog.logrocket.com/react-19-2-the-async-shift/
+- Reusable Actions article: https://certificates.dev/blog/building-reusable-components-with-react-19-actions