From 564d852c335a454162a3489cc9ad490086f26605 Mon Sep 17 00:00:00 2001 From: baptou12 Date: Thu, 6 Nov 2025 22:46:36 +0100 Subject: [PATCH 01/29] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20git=20commit?= =?UTF-8?q?=20guidelines=20with=20gitmoji=20and=20confidence=20index?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added comprehensive Git Commit Guidelines section to CLAUDE.md including: - Atomic commit philosophy with pragmatic approach - Gitmoji convention table with 12 common emojis - Commit message format with confidence index in body (not title) - Examples at 3 confidence levels (omit for trivial, 85%, 70%) - Confidence index guidelines (95-100% to <50%) - Pragmatic grouping rules for commits - Note to keep commits tool-agnostic (no AI references) This helps maintain consistent, informative commit messages across the project. Confidence: 95% --- CLAUDE.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 2abc738..af6f816 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -32,6 +32,102 @@ - Example: `` - Access in tests with `screen.getByTestId('submit-button')` +## Git Commit Guidelines + +### Commit Philosophy +- **Atomic commits**: Each commit should represent a single logical change +- **Be pragmatic**: Don't over-split trivial changes (e.g., fixing a typo and formatting can be one commit) +- **Confidence index**: Add confidence level for non-trivial changes + +### Gitmoji Convention +Use gitmoji prefixes for clear commit intent. Common ones: + +| Gitmoji | Code | When to use | +|---------|------|-------------| +| ✨ | `:sparkles:` | New feature | +| πŸ› | `:bug:` | Bug fix | +| πŸ”§ | `:wrench:` | Configuration changes | +| πŸ“ | `:memo:` | Documentation | +| ♻️ | `:recycle:` | Refactoring | +| βœ… | `:white_check_mark:` | Add/update tests | +| 🎨 | `:art:` | Improve structure/format | +| ⚑️ | `:zap:` | Performance improvement | +| ♿️ | `:wheelchair:` | Accessibility improvements | +| πŸ”₯ | `:fire:` | Remove code/files | +| 🚨 | `:rotating_light:` | Fix linter warnings | +| πŸ”’οΈ | `:lock:` | Security fixes | + +See full list: [gitmoji.dev](https://gitmoji.dev) + +### Commit Message Format +``` + : + +[Optional body explaining what and why] + +[Confidence: X% - only for non-trivial changes] +[Optional reference to tasks: ref: .claude/tasks/XX-category.md#task-N] +``` + +### Examples + +**Simple, high confidence (omit confidence):** +``` +πŸ› fix: remove debug console.log in AssistantMessage +``` + +**Medium confidence with explanation:** +``` +♻️ refactor: extract magic numbers to constants + +Moved hardcoded values (inputHeight, simulationDelay) to src/lib/constants.ts +for better maintainability. + +Confidence: 85% +ref: .claude/tasks/03-code-quality.md#task-1 +``` + +**Complex change, lower confidence:** +``` +✨ feat: add webhook response validation + +Added try/catch wrapper and JSON validation to useChatWebhook. +Validates response.output exists before using it. + +Confidence: 70% - needs testing with actual webhook endpoints to verify +all edge cases are handled correctly. + +ref: .claude/tasks/02-critical-fixes.md#task-3 +``` + +### Confidence Index Guidelines + +| Confidence | When to use | +|------------|-------------| +| 95-100% | Trivial changes (typos, comments, obvious bugs) | +| 85-95% | Well-tested changes with clear requirements | +| 70-85% | Non-trivial changes that need validation | +| 50-70% | Experimental or complex changes | +| <50% | Proof of concept, requires review | + +**Note:** Omit confidence index for trivial changes (typos, formatting, obvious fixes) + +### Pragmatic Grouping Rules +**βœ… OK to group together:** +- Related formatting changes across files +- Multiple typo fixes in same PR +- Adding missing aria-labels to multiple components +- Updating multiple config files for same purpose + +**❌ Keep separate:** +- Feature + Bug fix +- Refactoring + New functionality +- Test changes + Implementation (unless tightly coupled) +- Breaking changes (always isolate) + +### Important Note +**Do NOT** include references to Claude Code or AI assistance in commit messages. Keep commits professional and tool-agnostic. The commit message should describe the change itself, not how it was created. + ## Architecture Notes - RESTful API integration via custom webhooks - Project structure: From 2180dc8cc217f7897c64904cb04614048d504183 Mon Sep 17 00:00:00 2001 From: baptou12 Date: Thu, 6 Nov 2025 22:47:17 +0100 Subject: [PATCH 02/29] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20task=20manag?= =?UTF-8?q?ement=20structure=20in=20.claude/tasks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created organized task files to track project improvements: - README.md: Overview with 21 tasks across 4 categories - 01-documentation.md: 7 documentation alignment tasks (45min) - 02-critical-fixes.md: 5 urgent fixes including console.log, accessibility (30min) - 03-code-quality.md: 5 code quality improvements (60min) - 04-testing.md: 4 testing tasks for hooks and components (120min) Each task includes: - YAML frontmatter with metadata (priority, time, status) - Detailed problem description with file locations and line numbers - Step-by-step action items with code examples - Files to modify list - Why it's important explanation Total: 21 tasks, ~255 minutes of work identified. Confidence: 90% --- .claude/settings.local.json | 12 + .claude/tasks/01-documentation.md | 215 +++++++++++ .claude/tasks/02-critical-fixes.md | 281 ++++++++++++++ .claude/tasks/03-code-quality.md | 447 ++++++++++++++++++++++ .claude/tasks/04-testing.md | 585 +++++++++++++++++++++++++++++ .claude/tasks/README.md | 49 +++ 6 files changed, 1589 insertions(+) create mode 100644 .claude/settings.local.json create mode 100644 .claude/tasks/01-documentation.md create mode 100644 .claude/tasks/02-critical-fixes.md create mode 100644 .claude/tasks/03-code-quality.md create mode 100644 .claude/tasks/04-testing.md create mode 100644 .claude/tasks/README.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..4d5d48d --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,12 @@ +{ + "permissions": { + "allow": [ + "Bash(pnpm list:*)", + "Bash(mkdir:*)", + "Bash(git add:*)", + "Bash(git commit:*)" + ], + "deny": [], + "ask": [] + } +} diff --git a/.claude/tasks/01-documentation.md b/.claude/tasks/01-documentation.md new file mode 100644 index 0000000..2b95ab0 --- /dev/null +++ b/.claude/tasks/01-documentation.md @@ -0,0 +1,215 @@ +--- +title: Documentation Tasks +category: documentation +priority: low +total_tasks: 7 +estimated_time: 45min +status: pending +created: 2025-11-06 +--- + +# πŸ“š Documentation Tasks + +Tasks to align documentation with actual implementation. + +--- + +## Task 1: Fix /src/api Architecture Documentation + +**Status:** πŸ”² Pending +**Priority:** 🟒 Low +**Time:** ~5 min +**File:** `CLAUDE.md` + +### Problem +- Documentation mentions `/src/api` directory for "API integration and data fetching" +- This directory doesn't exist +- API calls are actually handled in `/src/hooks/useChatWebhook.ts` + +### Action +Remove or update the `/src/api` reference in CLAUDE.md line 40. + +**Option A:** Remove the line +**Option B:** Update to: +```markdown +- `/src/hooks`: Custom React hooks including API integration (useChatWebhook) +``` + +### Files to modify +- `CLAUDE.md` (line 40) + +--- + +## Task 2: Fix biome.json JSX Runtime Configuration + +**Status:** πŸ”² Pending +**Priority:** 🟒 Low +**Time:** ~2 min +**File:** `biome.json` + +### Problem +- `biome.json` line 16 sets `"jsxRuntime": "reactClassic"` +- Project uses React 19 with automatic JSX transformation +- Causes inconsistency with tsconfig `"jsx": "react-jsx"` + +### Action +Update `biome.json` line 16: + +```json +"jsxRuntime": "transparent" +``` + +Or remove the setting entirely to use default. + +### Files to modify +- `biome.json` (line 16) + +--- + +## Task 3: Update pnpm Version + +**Status:** πŸ”² Pending +**Priority:** 🟒 Low +**Time:** ~1 min +**File:** `CLAUDE.md` + +### Problem +- Documentation states `pnpm v10.6.3` +- Actual version is `pnpm v10.14.0` + +### Action +Update CLAUDE.md line 15: + +```markdown +- **Package Manager**: pnpm v10.14.0 +``` + +### Files to modify +- `CLAUDE.md` (line 15) + +--- + +## Task 4: Document Missing Folders + +**Status:** πŸ”² Pending +**Priority:** 🟒 Low +**Time:** ~5 min +**File:** `CLAUDE.md` + +### Problem +Actual project structure has folders not documented: +- `/src/domain` - Contains entities (Message, Roles enum) +- `/src/lib` - Utility functions (utils.ts with `cn()` helper) +- `/src/contexts` - Empty folder + +### Action +Add to CLAUDE.md "Architecture Notes" section: + +```markdown +- Project structure: + - `/src/components`: React components + - `/src/hooks`: Custom React hooks + - `/src/domain`: Domain entities and types + - `/src/lib`: Utility functions and helpers + - `/src/contexts`: React contexts (currently empty) +``` + +### Files to modify +- `CLAUDE.md` (lines 39-41) + +--- + +## Task 5: Update Naming Convention Documentation + +**Status:** πŸ”² Pending +**Priority:** 🟒 Low +**Time:** ~3 min +**File:** `CLAUDE.md` + +### Problem +- Documentation says: "Types/Interfaces: PascalCase with prefix (IUser, TConfig)" +- Actual codebase uses: `ChatContainerProps`, `WebhookResponse` (no I/T prefix) +- Uses "Props" suffix pattern instead + +### Action +Update CLAUDE.md line 21: + +```markdown +- **Naming Conventions**: + - Components: PascalCase + - Functions/Variables: camelCase + - Types/Interfaces: PascalCase (Props suffix for component props) + - Example: `ChatContainerProps`, `WebhookResponse` +``` + +### Files to modify +- `CLAUDE.md` (line 21) + +--- + +## Task 6: Document Key Dependencies + +**Status:** πŸ”² Pending +**Priority:** 🟒 Low +**Time:** ~10 min +**File:** `CLAUDE.md` + +### Problem +Important dependencies are used but not documented: +- `react-markdown` + `remark-gfm` - Markdown rendering +- `react-syntax-highlighter` - Code block syntax highlighting +- `lucide-react` - Icon library +- `class-variance-authority` - Component variants (used by shadcn) + +### Action +Add new section in CLAUDE.md after "UI Components": + +```markdown +- **Additional Libraries**: + - `react-markdown` + `remark-gfm`: Markdown rendering with GitHub flavored syntax + - `react-syntax-highlighter`: Code block highlighting in chat messages + - `lucide-react`: Icon library for UI elements + - `class-variance-authority`: Component variant utilities +``` + +### Files to modify +- `CLAUDE.md` (add after line 30) + +--- + +## Task 7: Decide on Empty /src/contexts Folder + +**Status:** πŸ”² Pending +**Priority:** 🟒 Low +**Time:** ~2 min +**File:** File system + +### Problem +- `/src/contexts` folder exists but is completely empty +- Not documented in CLAUDE.md +- Unclear if it's intentional or leftover + +### Action +**Option A:** Remove the folder if not needed: +```bash +rm -rf src/contexts +``` + +**Option B:** Keep and document intent in CLAUDE.md + +**Option C:** Add a README.md inside explaining it's reserved for future use + +### Files to modify +- Either delete `src/contexts/` or document it + +--- + +## Checklist + +- [ ] Task 1: Fix /src/api documentation +- [ ] Task 2: Fix biome.json jsxRuntime +- [ ] Task 3: Update pnpm version +- [ ] Task 4: Document missing folders +- [ ] Task 5: Update naming conventions +- [ ] Task 6: Document key dependencies +- [ ] Task 7: Handle empty contexts folder diff --git a/.claude/tasks/02-critical-fixes.md b/.claude/tasks/02-critical-fixes.md new file mode 100644 index 0000000..38da593 --- /dev/null +++ b/.claude/tasks/02-critical-fixes.md @@ -0,0 +1,281 @@ +--- +title: Critical Fixes +category: critical +priority: high +total_tasks: 5 +estimated_time: 30min +status: pending +created: 2025-11-06 +--- + +# πŸ”΄ Critical Fixes + +Urgent issues that should be fixed immediately. + +--- + +## Task 1: Remove Debug Console.log + +**Status:** πŸ”² Pending +**Priority:** πŸ”΄ Critical +**Time:** ~1 min +**File:** `src/components/chat/ChatMessage/AssistantMessage.tsx` + +### Problem +Line 34 contains a debug `console.log(style);` that was left in production code. + +### Location +```typescript +// src/components/chat/ChatMessage/AssistantMessage.tsx:34 +console.log(style); +``` + +### Action +Remove the entire line. + +### Why Critical? +- Pollutes browser console in production +- Exposes internal variable names +- Performance impact (minimal but unnecessary) + +### Files to modify +- `src/components/chat/ChatMessage/AssistantMessage.tsx` (line 34) + +--- + +## Task 2: Remove Duplicate Scroll Effect + +**Status:** πŸ”² Pending +**Priority:** πŸ”΄ Critical +**Time:** ~5 min +**File:** `src/components/chat/ChatContainer.tsx` + +### Problem +Two `useEffect` hooks doing the same scroll-to-bottom action: +- Lines 34-42: Has empty dependency array (never fires) +- Lines 44-49: Actually works with proper dependencies + +The first one is redundant and confusing. + +### Location +```typescript +// Lines 34-42 - REMOVE THIS +useEffect(() => { + if (scrollAreaRef.current) { + const viewport = scrollAreaRef.current.querySelector( + "[data-radix-scroll-area-viewport]", + ); + if (viewport) { + viewport.scrollTop = viewport.scrollHeight; + } + } +}, []); // Empty deps - never runs after initial mount +``` + +### Action +Delete lines 34-42 entirely. Keep only the second useEffect (lines 44-49). + +### Why Critical? +- Code duplication +- First effect with empty deps is misleading +- Makes code harder to maintain +- Could cause bugs if someone tries to "fix" it + +### Files to modify +- `src/components/chat/ChatContainer.tsx` (lines 34-42) + +--- + +## Task 3: Add Error Handling to Fetch + +**Status:** πŸ”² Pending +**Priority:** πŸ”΄ Critical +**Time:** ~10 min +**File:** `src/hooks/useChatWebhook.ts` + +### Problem +The `fetch` call has no try/catch block: +- Network errors not caught +- JSON parsing errors not handled +- No timeout handling +- Response validation missing + +### Location +```typescript +// Lines 44-56 - Current implementation +const response = await fetch(webhookUrl, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), +}); + +const data: WebhookResponse = await response.json(); +``` + +### Action +Wrap in try/catch with proper error handling: + +```typescript +try { + const response = await fetch(webhookUrl, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), + }); + + if (!response.ok) { + throw new Error(`HTTP ${response.status}: ${response.statusText}`); + } + + const data: WebhookResponse = await response.json(); + + // Validate response structure + if (!data || typeof data.output !== 'string') { + throw new Error('Invalid webhook response format'); + } + + return data; +} catch (error) { + console.error('Webhook error:', error); + throw new Error( + error instanceof Error + ? error.message + : 'Failed to communicate with webhook' + ); +} +``` + +### Why Critical? +- App crashes on network errors +- Poor user experience with vague errors +- No validation of API response +- Security risk (malformed responses) + +### Files to modify +- `src/hooks/useChatWebhook.ts` (lines 44-56) + +--- + +## Task 4: Add Aria-label to Textarea + +**Status:** πŸ”² Pending +**Priority:** πŸ”΄ Critical (Accessibility) +**Time:** ~2 min +**File:** `src/components/chat/ChatInput.tsx` + +### Problem +Textarea lacks `aria-label` for screen readers. Only placeholder text exists, which is not read by all assistive technologies. + +### Location +```typescript +// Current - no aria-label +