workflow-agent-cli 1.1.2

package/templates/LIBRARY_INVENTORY.md

@@ -0,0 +1,615 @@
+# Library Inventory
+
+> **Purpose**: This document serves as the single source of truth for all dependencies in the project. Agent must check this document before suggesting any new library and must update it when new libraries are approved.
+
+---
+
+## Table of Contents
+
+1. [Core Framework](#core-framework)
+2. [Backend & Data](#backend--data)
+3. [UI Components](#ui-components)
+4. [Forms & Validation](#forms--validation)
+5. [Drag & Drop](#drag--drop)
+6. [Rich Text Editing](#rich-text-editing)
+7. [Styling & Animation](#styling--animation)
+8. [Testing](#testing)
+9. [Utilities](#utilities)
+10. [Adding New Libraries](#adding-new-libraries)
+
+---
+
+## Core Framework
+
+### Next.js
+
+| Property      | Value                                                              |
+| ------------- | ------------------------------------------------------------------ |
+| Package       | `next`                                                             |
+| Version       | `^16.1.1`                                                          |
+| Purpose       | React framework with App Router, server components, server actions |
+| Documentation | https://nextjs.org/docs                                            |
+
+**Usage Patterns:**
+
+- App Router: All routes in `app/` directory
+- Server Actions: `'use server'` directive in `app/actions/`
+- Server Components: Default for pages, use `'use client'` for interactivity
+- Middleware: `middleware.ts` for auth redirects
+
+### React
+
+| Property      | Value                |
+| ------------- | -------------------- |
+| Package       | `react`, `react-dom` |
+| Version       | `^18.3.1`            |
+| Purpose       | UI library           |
+| Documentation | https://react.dev    |
+
+**Usage Patterns:**
+
+- Hooks: `useState`, `useEffect`, `useCallback`, `useMemo`, `useContext`
+- Context: Defined in `app/providers.tsx` (or `app/providers/`)
+- Custom hooks: `hooks/use*.tsx`
+
+### TypeScript
+
+| Property | Value           |
+| -------- | --------------- |
+| Package  | `typescript`    |
+| Version  | `^5.3.0`        |
+| Purpose  | Type safety     |
+| Config   | `tsconfig.json` |
+
+**Usage Patterns:**
+
+- Strict mode enabled
+- Path aliases: `@/*`, `@/components/*`, etc.
+- Types in `types/index.ts`, database types in `types/supabase.ts`
+
+---
+
+## Backend & Data
+
+### Supabase
+
+| Property      | Value                                                          |
+| ------------- | -------------------------------------------------------------- |
+| Packages      | `@supabase/supabase-js`, `@supabase/ssr`                       |
+| Versions      | `^2.89.0`, `^0.8.0`                                            |
+| Purpose       | Database (PostgreSQL), authentication, real-time subscriptions |
+| Documentation | https://supabase.com/docs                                      |
+
+**Usage Patterns:**
+
+```typescript
+// Browser client (singleton)
+import { getSupabaseClient } from '@/lib/supabase/client';
+
+// Server client (for server components/actions)
+import { createServerClient } from '@/lib/supabase/server';
+
+// Admin client (bypasses RLS)
+import { createAdminClient } from '@/lib/supabase/admin';
+```
+
+**Files:**
+
+- `lib/supabase/client.ts` - Browser client
+- `lib/supabase/server.ts` - Server client
+- `lib/supabase/admin.ts` - Admin client
+- `lib/supabase/middleware.ts` - Session refresh
+
+### TanStack Query (React Query)
+
+| Property      | Value                                           |
+| ------------- | ----------------------------------------------- |
+| Package       | `@tanstack/react-query`                         |
+| Version       | `^5.90.16`                                      |
+| Purpose       | Server state management, caching, data fetching |
+| Documentation | https://tanstack.com/query/latest               |
+
+**Usage Patterns:**
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+// Fetching data
+const { data, isLoading, error } = useQuery({
+  queryKey: ['tasks', boardId],
+  queryFn: () => getTasks(boardId),
+});
+
+// Mutations with cache invalidation
+const queryClient = useQueryClient();
+const mutation = useMutation({
+  mutationFn: createTask,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['tasks'] });
+  },
+});
+```
+
+---
+
+## UI Components
+
+### Radix UI Primitives
+
+| Property      | Value                               |
+| ------------- | ----------------------------------- |
+| Packages      | `@radix-ui/react-*` (20+ packages)  |
+| Purpose       | Unstyled, accessible UI primitives  |
+| Documentation | https://www.radix-ui.com/primitives |
+
+**Installed Primitives:**
+
+- `@radix-ui/react-accordion`
+- `@radix-ui/react-alert-dialog`
+- `@radix-ui/react-avatar`
+- `@radix-ui/react-checkbox`
+- `@radix-ui/react-collapsible`
+- `@radix-ui/react-context-menu`
+- `@radix-ui/react-dialog`
+- `@radix-ui/react-dropdown-menu`
+- `@radix-ui/react-hover-card`
+- `@radix-ui/react-label`
+- `@radix-ui/react-menubar`
+- `@radix-ui/react-navigation-menu`
+- `@radix-ui/react-popover`
+- `@radix-ui/react-progress`
+- `@radix-ui/react-radio-group`
+- `@radix-ui/react-scroll-area`
+- `@radix-ui/react-select`
+- `@radix-ui/react-separator`
+- `@radix-ui/react-slider`
+- `@radix-ui/react-slot`
+- `@radix-ui/react-switch`
+- `@radix-ui/react-tabs`
+- `@radix-ui/react-toggle`
+- `@radix-ui/react-toggle-group`
+- `@radix-ui/react-tooltip`
+
+**Usage**: Import from `components/ui/` which wraps Radix primitives with styling.
+
+### shadcn/ui Components
+
+| Property      | Value                                     |
+| ------------- | ----------------------------------------- |
+| Location      | `components/ui/`                          |
+| Purpose       | Pre-styled Radix components with Tailwind |
+| Documentation | https://ui.shadcn.com                     |
+
+**Available Components** (48 files in `components/ui/`):
+
+- Accordion, Alert, AlertDialog, Avatar
+- Badge, Button, Calendar, Card
+- Checkbox, Collapsible, Command, ContextMenu
+- Dialog, Drawer, DropdownMenu, Form
+- HoverCard, Input, Label, Menubar
+- NavigationMenu, Popover, Progress, RadioGroup
+- ScrollArea, Select, Separator, Sheet
+- Skeleton, Slider, Sonner (toasts), Switch
+- Table, Tabs, Textarea, Toast
+- Toggle, ToggleGroup, Tooltip
+- And more...
+
+**Usage Pattern:**
+
+```typescript
+import { Button } from '@/components/ui/button';
+import { Dialog, DialogContent, DialogHeader } from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+```
+
+### Lucide React (Icons)
+
+| Property      | Value                                  |
+| ------------- | -------------------------------------- |
+| Package       | `lucide-react`                         |
+| Version       | `0.487.0`                              |
+| Purpose       | Icon library (Feather icons successor) |
+| Documentation | https://lucide.dev                     |
+
+**Usage Pattern:**
+
+```typescript
+import { Plus, Trash, Settings, ChevronDown } from "lucide-react";
+
+<Button>
+  <Plus className="h-4 w-4 mr-2" />
+  Add Task
+</Button>
+```
+
+### Sonner (Toasts)
+
+| Property      | Value                        |
+| ------------- | ---------------------------- |
+| Package       | `sonner`                     |
+| Version       | `2.0.3`                      |
+| Purpose       | Toast notifications          |
+| Documentation | https://sonner.emilkowal.ski |
+
+**Usage Pattern:**
+
+```typescript
+import { toast } from 'sonner';
+
+toast.success('Task created successfully');
+toast.error('Failed to delete task');
+toast.loading('Saving changes...');
+```
+
+### Vaul (Drawer)
+
+| Property | Value                            |
+| -------- | -------------------------------- |
+| Package  | `vaul`                           |
+| Version  | `1.1.2`                          |
+| Purpose  | Mobile-friendly drawer component |
+
+### cmdk (Command Palette)
+
+| Property | Value                          |
+| -------- | ------------------------------ |
+| Package  | `cmdk`                         |
+| Version  | `1.1.1`                        |
+| Purpose  | Command palette / command menu |
+
+---
+
+## Forms & Validation
+
+### React Hook Form
+
+| Property      | Value                       |
+| ------------- | --------------------------- |
+| Package       | `react-hook-form`           |
+| Version       | `7.55.0`                    |
+| Purpose       | Form state management       |
+| Documentation | https://react-hook-form.com |
+
+**Usage Pattern:**
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const form = useForm<FormData>({
+  resolver: zodResolver(formSchema),
+  defaultValues: { title: '', description: '' },
+});
+```
+
+### Zod
+
+| Property      | Value                             |
+| ------------- | --------------------------------- |
+| Package       | `zod`                             |
+| Version       | `^4.3.2`                          |
+| Purpose       | Schema validation, type inference |
+| Documentation | https://zod.dev                   |
+
+**Usage Patterns:**
+
+```typescript
+import { z } from 'zod';
+
+// Define schema
+export const TaskSchema = z.object({
+  id: z.string().uuid(),
+  title: z.string().min(1).max(255),
+  priority: z.enum(['low', 'medium', 'high', 'critical']),
+});
+
+// Infer type from schema
+export type Task = z.infer<typeof TaskSchema>;
+
+// Validate data
+const result = TaskSchema.safeParse(data);
+if (!result.success) {
+  console.error(result.error);
+}
+```
+
+**Schema Files:** `lib/validations/*.schema.ts`
+
+---
+
+## Drag & Drop
+
+### react-dnd
+
+| Property      | Value                                                             |
+| ------------- | ----------------------------------------------------------------- |
+| Packages      | `react-dnd`, `react-dnd-html5-backend`, `react-dnd-touch-backend` |
+| Versions      | `16.0.1`, `16.0.1`, `^16.0.1`                                     |
+| Purpose       | Drag and drop for Kanban boards                                   |
+| Documentation | https://react-dnd.github.io/react-dnd                             |
+
+**Usage Pattern:**
+
+```typescript
+import { useDrag, useDrop } from "react-dnd";
+import { DndProvider } from "react-dnd";
+import { HTML5Backend } from "react-dnd-html5-backend";
+
+// In provider (already set up in app/providers.tsx)
+<DndProvider backend={HTML5Backend}>
+  {children}
+</DndProvider>
+
+// In draggable component
+const [{ isDragging }, drag] = useDrag({
+  type: "TASK",
+  item: { id: task.id },
+  collect: (monitor) => ({
+    isDragging: monitor.isDragging(),
+  }),
+});
+
+// In drop target
+const [{ isOver }, drop] = useDrop({
+  accept: "TASK",
+  drop: (item) => handleDrop(item),
+  collect: (monitor) => ({
+    isOver: monitor.isOver(),
+  }),
+});
+```
+
+---
+
+## Rich Text Editing
+
+### TipTap
+
+| Property      | Value                                                         |
+| ------------- | ------------------------------------------------------------- |
+| Packages      | `@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extension-*` |
+| Versions      | `^3.13.0`                                                     |
+| Purpose       | Rich text editor for task descriptions, comments              |
+| Documentation | https://tiptap.dev                                            |
+
+**Installed Extensions:**
+
+- `@tiptap/starter-kit` - Basic editing (bold, italic, lists, etc.)
+- `@tiptap/extension-image` - Image support
+- `@tiptap/extension-link` - Hyperlinks
+- `@tiptap/extension-mention` - @mentions
+- `@tiptap/extension-placeholder` - Placeholder text
+
+**Usage Location:** `components/RichTextEditor.tsx`, `components/EnhancedRichTextEditor.tsx`
+
+### DOMPurify
+
+| Property | Value                        |
+| -------- | ---------------------------- |
+| Package  | `dompurify`                  |
+| Version  | `^3.3.1`                     |
+| Purpose  | Sanitize HTML to prevent XSS |
+
+---
+
+## Styling & Animation
+
+### Tailwind CSS
+
+| Property | Value                                 |
+| -------- | ------------------------------------- |
+| Package  | `tailwindcss`, `@tailwindcss/postcss` |
+| Version  | `4.1.12`                              |
+| Purpose  | Utility-first CSS                     |
+| Config   | `postcss.config.mjs`, inline config   |
+
+### Class Utilities
+
+| Property | Value                                                    |
+| -------- | -------------------------------------------------------- |
+| Packages | `clsx`, `tailwind-merge`, `class-variance-authority`     |
+| Versions | `2.1.1`, `3.2.0`, `0.7.1`                                |
+| Purpose  | Conditional classes, merge conflicts, variant management |
+
+**Usage Pattern:**
+
+```typescript
+import { cn } from "@/lib/utils";  // combines clsx + tailwind-merge
+
+<div className={cn(
+  "base-styles",
+  isActive && "active-styles",
+  className
+)} />
+```
+
+### Motion (Framer Motion)
+
+| Property      | Value              |
+| ------------- | ------------------ |
+| Package       | `motion`           |
+| Version       | `12.23.24`         |
+| Purpose       | Animation library  |
+| Documentation | https://motion.dev |
+
+### next-themes
+
+| Property | Value                   |
+| -------- | ----------------------- |
+| Package  | `next-themes`           |
+| Version  | `0.4.6`                 |
+| Purpose  | Dark/light mode theming |
+
+---
+
+## Testing
+
+### Vitest (Unit Testing)
+
+| Property      | Value                                         |
+| ------------- | --------------------------------------------- |
+| Packages      | `vitest`, `@vitest/ui`, `@vitest/coverage-v8` |
+| Versions      | `^1.6.1`                                      |
+| Purpose       | Unit testing framework                        |
+| Config        | `vitest.config.ts`                            |
+| Documentation | https://vitest.dev                            |
+
+**Usage:**
+
+```bash
+pnpm test        # Run tests once
+pnpm test:watch  # Watch mode
+pnpm test:ui     # Visual UI
+pnpm test:coverage  # With coverage
+```
+
+### Playwright (E2E Testing)
+
+| Property      | Value                      |
+| ------------- | -------------------------- |
+| Package       | `@playwright/test`         |
+| Version       | `^1.57.0`                  |
+| Purpose       | End-to-end browser testing |
+| Config        | `playwright.config.ts`     |
+| Documentation | https://playwright.dev     |
+
+**Usage:**
+
+```bash
+pnpm test:e2e  # Run E2E tests
+```
+
+### Testing Library
+
+| Property | Value                                                                                |
+| -------- | ------------------------------------------------------------------------------------ |
+| Packages | `@testing-library/react`, `@testing-library/jest-dom`, `@testing-library/user-event` |
+| Versions | `^14.3.1`, `^6.9.1`, `^14.6.1`                                                       |
+| Purpose  | React component testing utilities                                                    |
+
+### MSW (Mock Service Worker)
+
+| Property | Value                      |
+| -------- | -------------------------- |
+| Package  | `msw`                      |
+| Version  | `^2.12.4`                  |
+| Purpose  | API mocking for tests      |
+| Handlers | `lib/test-utils/handlers/` |
+
+### jsdom
+
+| Property | Value                      |
+| -------- | -------------------------- |
+| Package  | `jsdom`                    |
+| Version  | `^24.1.3`                  |
+| Purpose  | DOM environment for Vitest |
+
+---
+
+## Utilities
+
+### date-fns
+
+| Property      | Value                |
+| ------------- | -------------------- |
+| Package       | `date-fns`           |
+| Version       | `3.6.0`              |
+| Purpose       | Date manipulation    |
+| Documentation | https://date-fns.org |
+
+**Usage Pattern:**
+
+```typescript
+import { format, parseISO, differenceInDays } from 'date-fns';
+
+format(new Date(), 'MMM d, yyyy'); // "Jan 8, 2026"
+differenceInDays(endDate, startDate);
+```
+
+### Recharts
+
+| Property | Value                         |
+| -------- | ----------------------------- |
+| Package  | `recharts`                    |
+| Version  | `2.15.2`                      |
+| Purpose  | Charts and data visualization |
+
+### Resend
+
+| Property | Value                                        |
+| -------- | -------------------------------------------- |
+| Package  | `resend`                                     |
+| Version  | `^6.6.0`                                     |
+| Purpose  | Transactional email (invites, notifications) |
+
+### Faker.js
+
+| Property | Value                                  |
+| -------- | -------------------------------------- |
+| Package  | `@faker-js/faker`                      |
+| Version  | `^10.1.0`                              |
+| Purpose  | Generate fake data for testing/seeding |
+
+### Other Utilities
+
+| Package                    | Version   | Purpose                 |
+| -------------------------- | --------- | ----------------------- |
+| `react-day-picker`         | `8.10.1`  | Date picker component   |
+| `react-resizable-panels`   | `2.1.7`   | Resizable panel layouts |
+| `react-responsive-masonry` | `2.7.1`   | Masonry grid layout     |
+| `embla-carousel-react`     | `8.6.0`   | Carousel component      |
+| `input-otp`                | `1.4.2`   | OTP input component     |
+| `react-popper`             | `2.3.0`   | Popper positioning      |
+| `@popperjs/core`           | `2.11.8`  | Popper core             |
+| `tippy.js`                 | `^6.3.7`  | Tooltip library         |
+| `@use-gesture/react`       | `^10.3.1` | Gesture handling        |
+
+---
+
+## Adding New Libraries
+
+### Process
+
+1. **Check this document first** - Ensure the functionality isn't already covered
+2. **Propose the library** - Explain why it's needed and alternatives considered
+3. **Get approval** - Do not add without explicit user approval
+4. **Install** - Add to `package.json` with appropriate version
+5. **Document** - Add entry to this file following the format above
+6. **Example** - Add usage example in the relevant source file
+
+### Documentation Template
+
+When adding a new library, use this template:
+
+```markdown
+### [Library Name]
+
+| Property      | Value             |
+| ------------- | ----------------- |
+| Package       | `package-name`    |
+| Version       | `x.x.x`           |
+| Purpose       | Brief description |
+| Documentation | https://...       |
+
+**Usage Patterns:**
+\`\`\`typescript
+// Code example
+\`\`\`
+
+**Files:** Where it's primarily used
+```
+
+---
+
+## MUI (Legacy - Consider Migration)
+
+> ⚠️ **Note**: MUI packages are installed but the project primarily uses Radix/shadcn. Consider removing if not actively used.
+
+| Packages              | Versions  |
+| --------------------- | --------- |
+| `@mui/material`       | `7.3.5`   |
+| `@mui/icons-material` | `7.3.5`   |
+| `@emotion/react`      | `11.14.0` |
+| `@emotion/styled`     | `11.14.1` |
+
+If these are only used in specific legacy components, consider migrating to Radix equivalents.