@minhduydev/mdpi 0.4.1 → 0.6.0

package/dist/template/.pi/skills/zustand/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: zustand
+description: Use when implementing global or shared state management in React with Zustand v5. Covers store creation, slices pattern, middleware, selective subscriptions, React 19 + SSR integration. MUST load before any state management implementation.
+---
+
+# Zustand v5
+
+## When to Use
+
+- Managing global or shared client-side state in React
+- Replacing Redux, Jotai, or Context for state management
+- Creating stores that are used across multiple components
+- Implementing slices for domain-separated state
+- Persisting state to localStorage or sessionStorage
+- Using middleware (immer, devtools, persist)
+
+## When NOT to Use
+
+- Server state (use TanStack Query or Server Components)
+- Form state (use React Hook Form or Server Actions)
+- Single-component local state (use `useState` or `useReducer`)
+- Server Components (Zustand is client-only)
+
+## Setup
+
+```bash
+npm install zustand
+```
+
+## Basic Store
+
+```tsx
+// stores/counter.ts
+import { create } from 'zustand'
+
+interface CounterState {
+  count: number
+  increment: () => void
+  decrement: () => void
+  reset: () => void
+}
+
+export const useCounterStore = create<CounterState>((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+  reset: () => set({ count: 0 }),
+}))
+```
+
+```tsx
+// components/Counter.tsx
+'use client'
+
+import { useCounterStore } from '@/stores/counter'
+
+export function Counter() {
+  const { count, increment, decrement } = useCounterStore()
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>-</button>
+    </div>
+  )
+}
+```
+
+## Slices Pattern
+
+Split store into domain slices:
+
+```tsx
+// stores/index.ts
+import { create } from 'zustand'
+import { createAuthSlice, type AuthSlice } from './slices/auth'
+import { createCartSlice, type CartSlice } from './slices/cart'
+
+type Store = AuthSlice & CartSlice
+
+export const useStore = create<Store>()((...args) => ({
+  ...createAuthSlice(...args),
+  ...createCartSlice(...args),
+}))
+```
+
+```tsx
+// stores/slices/auth.ts
+import type { StateCreator } from 'zustand'
+
+export interface AuthSlice {
+  user: User | null
+  login: (credentials: Credentials) => Promise<void>
+  logout: () => void
+}
+
+export const createAuthSlice: StateCreator<AuthSlice, [], [], AuthSlice> = (set) => ({
+  user: null,
+  login: async (credentials) => {
+    const user = await api.login(credentials)
+    set({ user })
+  },
+  logout: () => set({ user: null }),
+})
+```
+
+## Selective Subscriptions
+
+Zustand re-renders only when **used** state changes:
+
+```tsx
+// ❌ Whole store — re-renders on any change
+const { count, name } = useStore()
+
+// ✅ Selective — re-renders only when count changes
+const count = useStore((state) => state.count)
+const increment = useStore((state) => state.increment) // Stable reference
+
+// ✅ Multiple values — useShallow for objects
+import { useShallow } from 'zustand/react/shallow'
+
+const { name, email } = useStore(
+  useShallow((state) => ({ name: state.user.name, email: state.user.email }))
+)
+```
+
+`useShallow` does shallow equality — avoids re-render when both values are the same.
+
+## Middleware
+
+### Persist (localStorage)
+
+```tsx
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+export const useSettingsStore = create(
+  persist(
+    (set) => ({
+      theme: 'light',
+      setTheme: (theme: 'light' | 'dark') => set({ theme }),
+    }),
+    {
+      name: 'app-settings',  // localStorage key
+      partialize: (state) => ({ theme: state.theme }),  // Only persist theme
+    }
+  )
+)
+```
+
+### Immer (Immutable Updates)
+
+```tsx
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+export const useTodoStore = create(
+  immer((set) => ({
+    todos: [] as Todo[],
+    addTodo: (text: string) =>
+      set((state) => {
+        state.todos.push({ id: crypto.randomUUID(), text, done: false })
+      }),
+    toggleTodo: (id: string) =>
+      set((state) => {
+        const todo = state.todos.find((t) => t.id === id)
+        if (todo) todo.done = !todo.done
+      }),
+  }))
+)
+```
+
+### DevTools
+
+```tsx
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+export const useStore = create(
+  devtools(
+    (set) => ({
+      count: 0,
+      increment: () => set((s) => ({ count: s.count + 1 }), false, 'increment'),
+    }),
+    { name: 'AppStore' }  // Name in Redux DevTools
+  )
+)
+```
+
+### Combining Multiple Middleware
+
+```tsx
+import { create } from 'zustand'
+import { devtools, persist, immer } from 'zustand/middleware'
+
+export const useStore = create(
+  devtools(
+    persist(
+      immer((set) => ({
+        // store...
+      })),
+      { name: 'app-storage' }
+    ),
+    { name: 'AppStore' }
+  )
+)
+```
+
+## React 19 + Server Components
+
+Zustand is **client-only**. Pattern for Next.js App Router:
+
+```tsx
+// stores/useStore.ts
+import { create } from 'zustand'
+
+export const useStore = create<Store>((set) => ({
+  // ...
+}))
+```
+
+```tsx
+// components/ClientWrapper.tsx
+'use client'
+
+import { useStore } from '@/stores/useStore'
+
+export function ClientWrapper({ children }) {
+  const data = useStore((s) => s.data)
+
+  return <div>{children}</div>
+}
+```
+
+**Rules**:
+- Stores are defined outside components (module scope)
+- Store consumers must be in `'use client'` components
+- Server Components can import the store type but cannot `useStore()`
+- Use React Context to provide a store instance if you need SSR hydration
+
+## SSR Hydration Pattern
+
+```tsx
+// app/providers.tsx
+'use client'
+
+import { type ReactNode, createContext, useContext, useRef } from 'react'
+import { type StoreApi, useStore } from 'zustand'
+
+// Create context for store
+const StoreContext = createContext<StoreApi<AppStore> | null>(null)
+
+export function StoreProvider({ children }: { children: ReactNode }) {
+  const storeRef = useRef<StoreApi<AppStore>>()
+
+  if (!storeRef.current) {
+    storeRef.current = createAppStore()
+  }
+
+  return (
+    <StoreContext.Provider value={storeRef.current}>
+      {children}
+    </StoreContext.Provider>
+  )
+}
+
+// Hook to use the store
+export function useAppStore<T>(selector: (state: AppStore) => T): T {
+  const store = useContext(StoreContext)
+  if (!store) throw new Error('Missing StoreProvider')
+  return useStore(store, selector)
+}
+```
+
+## Async Actions
+
+```tsx
+// Async actions are just async functions in the store:
+interface UserStore {
+  user: User | null
+  loading: boolean
+  error: Error | null
+  fetchUser: (id: string) => Promise<void>
+}
+
+export const useUserStore = create<UserStore>((set) => ({
+  user: null,
+  loading: false,
+  error: null,
+  fetchUser: async (id) => {
+    set({ loading: true, error: null })
+    try {
+      const user = await api.getUser(id)
+      set({ user, loading: false })
+    } catch (error) {
+      set({ error: error as Error, loading: false })
+    }
+  },
+}))
+```
+
+## When to Use Zustand vs Context vs TanStack Query
+
+| Tool | Best for |
+|------|----------|
+| **Zustand** | Global client state: theme, auth, cart, UI preferences |
+| **React Context** | Dependency injection, theming, auth provider — static values that rarely change |
+| **TanStack Query** | Server state: data fetching, caching, mutations |
+| **useState/useReducer** | Local component state |
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Using Zustand for server state | Use TanStack Query for fetched data — Zustand for client-only state |
+| `useStore()` without selector — re-renders on any change | Always use selectors: `useStore(s => s.count)` |
+| Multiple values returned as new object every render | Use `useShallow` for object selectors |
+| Store in Server Component | Move store usage to `'use client'` |
+| `getState()` in render | `getState()` is for callbacks/outside React, not render |
+| Large stores with everything in one file | Use slices pattern to separate domains |
+| Recreating store on every render | Define store outside component or use `useRef` for context pattern |
+
+## Verification
+
+- [ ] Store defined outside component (module scope) or via `useRef` in provider
+- [ ] All store consumers are in `'use client'` components
+- [ ] Selectors used for granular subscriptions — no destructured `useStore()`
+- [ ] `useShallow` used for multi-value object selectors
+- [ ] Server state (fetched data) managed by TanStack Query, not Zustand
+- [ ] Slices pattern used for stores with multiple domains
+- [ ] `persist` middleware configured with `partialize` to avoid storing sensitive data
+- [ ] DevTools middleware enabled (development only)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhduydev/mdpi",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "CLI to scaffold and manage a Pi coding-agent kit (.pi/) in any repo",
   "keywords": [
     "pi",

package/dist/template/.pi/context/fallow.md

@@ -1,137 +0,0 @@
----
-purpose: Fallow codebase intelligence commands for AI agents — dead code, duplication, complexity, and audit gating
-updated: 2026-06-04
----
-
-# Fallow — Codebase Intelligence Reference
-
-## Overview
-
-Fallow is a Rust-native, deterministic static analysis tool for TypeScript/JavaScript codebases.
-**No AI inside the analyzer** — same input always produces the same output.
-It builds a complete module graph to find issues no linter or type checker can see.
-
----
-
-## Commands
-
-### Full Analysis (single pass)
-
-```bash
-npx fallow                      # All analyses: dead code + duplication + health
-npx fallow --format json        # Structured output for agent parsing
-```
-
-### Dead Code
-
-```bash
-npx fallow dead-code                                   # Full dead code report
-npx fallow dead-code --format json --quiet              # JSON for agents
-npx fallow dead-code --unused-exports                   # Only unused exports
-npx fallow dead-code --unused-dependencies              # Only unused deps
-npx fallow dead-code --circular                         # Only circular deps
-npx fallow fix --dry-run                                # Preview safe auto-fixes
-npx fallow fix --yes                                    # Apply auto-fixes
-```
-
-### Trace (investigate before deleting)
-
-```bash
-npx fallow dead-code --trace FILE:EXPORT_NAME           # Why is this export flagged?
-npx fallow dead-code --trace-dependency PACKAGE_NAME    # Where is this dep imported?
-```
-
-### Duplication
-
-```bash
-npx fallow dupes                     # Find code clones
-npx fallow dupes --mode strict       # Exact matches only
-npx fallow dupes --mode weak         # Structural matches
-npx fallow dupes --trace FILE:LINE   # Deep-dive a specific clone group
-```
-
-### Health (complexity)
-
-```bash
-npx fallow health                    # Complexity hotspots + refactoring targets
-npx fallow health --format json      # Structured output
-```
-
-### Audit Gate (for CI / pre-commit)
-
-```bash
-npx fallow audit                     # Check changed files (verdict: pass/warn/fail)
-npx fallow audit --format json       # Structured verdict for agents
-npx fallow audit --gate new-only     # Only flag new issues, not pre-existing
-```
-
----
-
-## Workflow Patterns
-
-### Post-Edit Verification Loop
-
-```bash
-# 1. Make changes
-# 2. Run audit
-npx fallow audit --format json --quiet
-# 3. If verdict is "fail", inspect findings
-# 4. Fix or investigate with --trace
-# 5. Re-run audit until pass
-```
-
-### Codebase Cleanup
-
-```bash
-npx fallow                           # Full picture
-npx fallow dead-code --format json   # Find unused code
-npx fallow fix --dry-run             # Preview auto-removals
-npx fallow fix --yes                 # Apply auto-fixes
-npx fallow dupes                     # Find duplication
-npx fallow health                    # Find complexity hotspots
-```
-
-### Monorepo / Workspace
-
-```bash
-npx fallow --workspace               # Analyze all workspaces
-npx fallow --workspace packages/pkg  # Analyze specific workspace
-```
-
----
-
-## Understanding Output
-
-Every finding in `--format json` includes:
-
-```json
-{
-  "path": "src/utils/example.ts:42",
-  "issue_type": "unused-exports",
-  "actions": [
-    {
-      "type": "delete-export",
-      "auto_fixable": true,
-      "description": "Remove unused export"
-    }
-  ]
-}
-```
-
-The `actions[]` array is machine-actionable. Agents can inspect `auto_fixable` flags and apply safe fixes programmatically.
-
----
-
-## Config
-
-Fallow auto-detects your project. For custom config, run:
-
-```bash
-npx fallow init    # Generates .fallow/config.yaml with auto-detected settings
-```
-
-Common config patterns:
-- `ignorePatterns` — exclude directories from analysis (e.g., `.pi/`)
-- `entry` — declare additional entry points
-- `publicPackages` — packages with public API surface
-- `rules` — custom issue severity rules

package/dist/template/.pi/prompts/loop-check.md

@@ -1,87 +0,0 @@
----
-description: NO-GO qualification gate — decide whether a task is safe to run as an unattended loop
-argument-hint: "<task description> [--help]"
----
-
-# Loop-Check: $ARGUMENTS
-
-Qualify a task before it is ever scheduled as an unattended loop. Emit a single GO/NO-GO verdict with the cited condition that produced it. This prompt is the gate *before* the gate — it refuses work a loop cannot honestly judge.
-
-> Refuse first, test second, checklist last. Never let "looks automatable" override the refuse-list.
-
-## Parse Arguments
-
-| Argument       | Default  | Description                                      |
-| ------------- | -------- | ------------------------------------------------ |
-| `<task>`      | required | The task proposed for unattended looping          |
-| `--help`      | false    | Show this usage                                   |
-
-## Step 1 — Refuse-List (Immediate NO-GO)
-
-If the task touches any of these, **stop here** and emit NO-GO. Do not proceed to the 2-condition test.
-
-- **auth** — login, sessions, tokens, permissions, auth flows, auth module rewrites
-- **payments** — billing, checkout, refunds, subscriptions, payment provider integration
-- **architecture** — framework/library switches, schema migrations, new DB tables, new services, breaking API changes
-
-> Rationale: these need human judgement a loop cannot provide. The refuse-list is the honest ceiling, not a configurable preference.
-
-If a refuse-list category is hit → `CONDITION: <refused category> refused` (e.g. `CONDITION: architecture refused`).
-
-## Step 2 — The 2-Condition Test
-
-Both conditions must hold. If either fails, emit NO-GO citing the failed condition.
-
-1. **Verification is automated.** There exists an objective command whose **exit code** decides pass/fail — `npm test`, `tsc --noEmit`, `eslint`, a custom gate script. The stop condition is computational (exit code), never an LLM's opinion. If the only "check" is "the agent says it looks good" → FAIL.
-2. **The token budget absorbs the waste.** The cost of one wasted run (gate fails, no-op, early-exit) is small enough that running on the scheduled cadence does not blow the budget. If a single failed run is expensive (large model, long context, many turns) and there is no per-run cap → FAIL.
-
-If condition 1 fails → `CONDITION: verification not automated (no exit-code gate)`.
-If condition 2 fails → `CONDITION: budget does not absorb waste (uncapped/expensive failed run)`.
-
-## Step 3 — 30-Second Checklist
-
-Confirm every item. Any miss → NO-GO citing the missing item.
-
-- [ ] **Objective gate exists** — a named command with a pass = exit 0 contract (write it down; "tests" without a command is not a gate).
-- [ ] **Hard stop exists** — a non-negotiable exit condition: repeated gate failure, budget cap hit, or forbidden path touched. The loop exits; it does not improvise.
-- [ ] **Human approves merge/deploy/dependency changes** — the loop may open PRs and stage work; a human merges, deploys, and changes deps. No auto-merge.
-
-Missing gate → `CONDITION: no objective gate`.
-Missing hard stop → `CONDITION: no hard stop`.
-No human-approval boundary → `CONDITION: no human-approval boundary on merge/deploy/deps`.
-
-## Step 4 — Emit Verdict
-
-Output **exactly** these two lines and nothing else as the decision:
-
-```
-VERDICT: GO
-CONDITION: verification automated + budget absorbs waste
-```
-
-or
-
-```
-VERDICT: NO-GO
-CONDITION: <cited condition from Step 1, 2, or 3>
-```
-
-- `VERDICT` is `GO` or `NO-GO` — no other values.
-- `CONDITION` cites the specific condition that produced the verdict. For GO, cite both passing conditions. For NO-GO, cite the first failing condition (Step 1 overrides Step 2 overrides Step 3).
-- Do not add rationale, recommendations, or next steps after the verdict lines. The verdict is the contract.
-
-## Worked Examples
-
-- **"triage failing CI nightly"** with `npm test` gate, no-op early-exit <5k tokens → `VERDICT: GO` / `CONDITION: verification automated + budget absorbs waste`
-- **"rewrite auth module"** → `VERDICT: NO-GO` / `CONDITION: auth refused`
-- **"migrate from REST to GraphQL"** → `VERDICT: NO-GO` / `CONDITION: architecture refused`
-- **"keep docs in sync with code weekly"** with no gate command → `VERDICT: NO-GO` / `CONDITION: verification not automated (no exit-code gate)`
-
-## Related
-
-| Companion | Role |
-|---|---|
-| `loop-engineering` skill | The 2-condition test, refuse-list, and 5 building blocks this gate codifies |
-| `/loop-init` | Scaffold `.pi/loops/<name>/` once a task is GO |
-| `/loop-review` | Maker/checker verification — the gate *during* a run |
-| `loop-audit` | Readiness scoring (L0-L3) for an already-GO loop |