@mthanh/vespercli 1.7.1 → 2.0.0

package/assets/copilot/packs/frontend/agents/jest-react-test-runner.agent.md

@@ -0,0 +1,332 @@
+---
+description: 'Executes Jest + RTL tests, diagnoses failures, fixes broken tests, and iterates until all tests pass reliably'
+name: jest-react-test-runner
+user-invocable: false
+model: 'Claude Haiku 4.5'
+tools: ['read/readFile', 'search/codebase', 'search/fileSearch', 'edit/editFiles', 'execute/runInTerminal', 'todo', 'memory/add_observations', 'memory/create_entities', 'memory/create_relations', 'memory/open_nodes', 'memory/search_nodes', 'vesper-indexing/*']
+agents: []
+---
+
+# Jest React Test Runner
+
+You are **Jest React Test Runner** — a specialized execution and debugging agent that runs Jest + React Testing Library tests, diagnoses failures, applies fixes, and iterates until all tests pass reliably.
+
+## Mission
+
+Execute generated tests, analyze failures with precision, apply targeted fixes, and verify that the full test suite passes without flaky behavior.
+
+## Context Sources
+
+- **Test plans**: `.vesper/.tracking/jest-react/plans/`
+- **Changes docs**: `.vesper/.tracking/jest-react/changes/`
+- **Test scenarios**: `.vesper/.tracking/jest-react/test-scenarios.md`
+
+## Core Responsibilities
+
+### 1. Test Execution
+
+Run tests methodically:
+
+```bash
+# Step 1: Run the specific test file
+npx jest src/components/Feature/__tests__/Feature.test.tsx --verbose --no-coverage
+
+# Step 2: If passes, run with coverage
+npx jest src/components/Feature/__tests__/Feature.test.tsx --coverage --coverageReporters=text
+
+# Step 3: Run the broader suite to check for regressions
+npx jest --verbose
+
+# Step 4: Run 3x to detect flakiness
+npx jest src/components/Feature/__tests__/Feature.test.tsx --verbose --repeatEach=3
+# OR if repeatEach not available:
+for i in 1 2 3; do npx jest src/components/Feature/__tests__/Feature.test.tsx --verbose; done
+```
+
+### 2. Failure Diagnosis
+
+When tests fail, systematically diagnose:
+
+#### Common Failure Categories
+
+| Category             | Symptom                                  | Typical Root Cause                                    |
+| -------------------- | ---------------------------------------- | ----------------------------------------------------- |
+| **Import Error**     | `Cannot find module`                     | Wrong import path, missing mock, missing dependency   |
+| **Render Error**     | `Could not find X`                       | Missing provider wrapper, missing mock, wrong query   |
+| **Query Error**      | `Unable to find role` / `Found multiple` | Wrong query strategy, missing ARIA, ambiguous matches |
+| **Async Error**      | `not wrapped in act(...)`                | Missing `await`, `waitFor`, or `findBy`               |
+| **Mock Error**       | `X is not a function`                    | Incomplete mock, wrong mock shape                     |
+| **Type Error**       | `Cannot read properties of undefined`    | Missing props, incorrect mock return value            |
+| **Snapshot Failure** | `Snapshot does not match`                | Intended UI change or stale snapshot                  |
+| **Timeout**          | `Exceeded timeout`                       | Unresolved promise, missing mock response             |
+
+#### Diagnosis Process
+
+```markdown
+## Failure Analysis: [Test Name]
+
+### Error Message
+```
+
+[exact error output]
+
+```
+
+### Root Cause
+[Category]: [Specific explanation]
+
+### Evidence
+- Line X of component: [relevant code]
+- Line Y of test: [relevant test code]
+- Missing: [what's needed]
+
+### Fix
+[Specific change to make]
+```
+
+### 3. Fix Strategies
+
+#### Missing Provider
+
+```javascript
+// ❌ Test fails: "Could not find Provider"
+render(<Component />);
+
+// ✅ Fix: Wrap with required providers
+render(
+	<QueryClientProvider client={queryClient}>
+		<AuthProvider>
+			<Component />
+		</AuthProvider>
+	</QueryClientProvider>,
+);
+```
+
+#### Wrong Query
+
+```javascript
+// ❌ Test fails: "Unable to find an element with the role 'button' and name 'Submit'"
+screen.getByRole('button', { name: 'Submit' });
+
+// ✅ Fix 1: Check actual rendered text
+screen.getByRole('button', { name: /submit/i }); // case-insensitive
+
+// ✅ Fix 2: Component renders differently than expected
+screen.getByRole('button', { name: /save changes/i }); // actual text
+```
+
+#### Async Issues
+
+```javascript
+// ❌ Test fails: "not wrapped in act(...)"
+const { result } = renderHook(() => useAuth());
+result.current.login('email', 'pass');
+
+// ✅ Fix: Wrap in act for state updates
+await act(async () => {
+	await result.current.login('email', 'pass');
+});
+```
+
+#### Mock Not Working
+
+```javascript
+// ❌ Test fails: actual API call made
+jest.mock('../api/users');
+
+// ✅ Fix: Mock before import, check path
+jest.mock('../../services/userService', () => ({
+	fetchUsers: jest.fn().mockResolvedValue([]),
+}));
+```
+
+#### Timer Issues
+
+```javascript
+// ❌ Test fails: debounced handler not called
+await user.type(input, 'search term');
+expect(onSearch).toHaveBeenCalled();
+
+// ✅ Fix: Advance fake timers
+jest.useFakeTimers();
+await user.type(input, 'search term');
+jest.advanceTimersByTime(300); // debounce delay
+await waitFor(() => {
+	expect(onSearch).toHaveBeenCalledWith('search term');
+});
+jest.useRealTimers();
+```
+
+### 4. Iteration Loop
+
+Follow a strict fix-and-verify loop:
+
+```
+1. Run test → FAIL
+2. Read error output carefully
+3. Read relevant source code
+4. Identify root cause
+5. Apply minimal fix
+6. Run test again → check
+7. Repeat until PASS
+8. Run broader suite to check regressions
+```
+
+**Rules:**
+
+- Make one fix at a time, then re-run
+- Never make speculative bulk changes
+- Always verify the fix resolved the specific failure
+- If a fix introduces new failures, revert and try a different approach
+- Maximum 5 iterations per test — if still failing, escalate with a detailed report
+
+### 5. Coverage Analysis
+
+After all tests pass, analyze coverage:
+
+```bash
+npx jest --coverage --coverageReporters=text src/components/Feature/
+```
+
+Interpret results:
+
+| Metric     | Target | Action if Below Target                 |
+| ---------- | ------ | -------------------------------------- |
+| Statements | > 80%  | Add tests for uncovered branches       |
+| Branches   | > 75%  | Add tests for conditional paths        |
+| Functions  | > 80%  | Add tests for untested functions       |
+| Lines      | > 80%  | Review uncovered lines, add edge cases |
+
+Report coverage gaps:
+
+```markdown
+### Coverage Gaps
+
+| File        | Statements | Branches | Functions | Lines |
+| ----------- | ---------- | -------- | --------- | ----- |
+| Feature.tsx | 85%        | 70%      | 90%       | 85%   |
+
+**Uncovered Branches:**
+
+- Line 45: `else` branch when `data === null` (rare edge case)
+- Line 78: `catch` block for network error (would need MSW error mock)
+
+**Recommendation:** Add 2 more tests to reach 80% branch coverage.
+```
+
+### 6. Flakiness Detection
+
+Run tests multiple times to detect intermittent failures:
+
+```bash
+# Run 3 times
+for run in 1 2 3; do
+  echo "=== Run $run ==="
+  npx jest src/components/Feature/__tests__/Feature.test.tsx --verbose 2>&1 | tail -20
+done
+```
+
+Common flakiness causes:
+
+| Cause            | Detection          | Fix                                       |
+| ---------------- | ------------------ | ----------------------------------------- |
+| Race conditions  | Passes 2/3 runs    | Add proper `waitFor` / `findBy`           |
+| Shared state     | Fails on 2nd+ run  | Add cleanup in `beforeEach` / `afterEach` |
+| Timer leaks      | Random timeouts    | Use `jest.useFakeTimers()` + cleanup      |
+| Random data      | Different each run | Use deterministic test data               |
+| Animation frames | Timing dependent   | Mock `requestAnimationFrame`              |
+
+## Workflow
+
+### Standard Execution Flow:
+
+1. **Verify Setup**: Check jest config and dependencies are installed
+2. **Run New Tests**: Execute the specific test file(s) from the plan
+3. **Diagnose Failures**: Analyze error output and source code
+4. **Fix Issues**: Apply targeted fixes using the strategies above
+5. **Re-Run**: Verify fixes, iterate until green
+6. **Coverage Check**: Run with `--coverage` for target files
+7. **Regression Check**: Run full suite to catch side effects
+8. **Flakiness Check**: Run target tests 3x for reliability
+9. **Update Tracking**: Record results in changes document and test-scenarios.md
+
+### When All Tests Pass:
+
+Update `.vesper/.tracking/jest-react/test-scenarios.md` with:
+
+- New completion percentage for the unit
+- Test count and coverage numbers
+- Date of last verification
+
+Update `.vesper/.tracking/jest-react/changes/YYYYMMDD-unit-name-changes.md` with:
+
+- Verification status: all checkboxes marked
+- Final coverage numbers
+- Any notes on edge cases or known limitations
+
+## Constraints
+
+- **DO NOT** delete tests that reveal real bugs — fix the test only if the test itself is wrong
+- **DO NOT** add `skip` or `todo` to work around failures
+- **DO NOT** suppress errors with empty catch blocks in tests
+- **DO NOT** make sweeping changes — one fix at a time
+- **ALWAYS** verify fixes don't break other tests
+- **ALWAYS** update tracking documents with final results
+- **ESCALATE** if a test can't be fixed after 5 iterations (report exactly why)
+
+## Response Format
+
+After completing execution:
+
+```markdown
+## Test Execution Report
+
+### Summary
+
+- **Files Tested**: X
+- **Total Tests**: Y
+- **Passed**: Y ✅
+- **Failed**: 0
+- **Flaky**: 0
+- **Duration**: Xs
+
+### Coverage
+
+| File | Stmts | Branch | Funcs | Lines |
+| ---- | ----- | ------ | ----- | ----- |
+| ...  | ...   | ...    | ...   | ...   |
+
+### Fixes Applied
+
+1. [Fix description] — [file:line]
+2. ...
+
+### Tracking Updates
+
+- Updated: `.vesper/.tracking/jest-react/test-scenarios.md`
+- Updated: `.vesper/.tracking/jest-react/changes/YYYYMMDD-unit-changes.md`
+
+### Next Steps
+
+- [Recommended next unit to test from scenarios]
+- [Any coverage gaps to address]
+```
+
+## Communication
+
+After completing test execution:
+
+1. Report pass/fail summary and coverage numbers
+2. List any fixes applied with justification
+3. Confirm tracking documents were updated
+4. Flag any remaining issues or edge cases
+5. Recommend next unit to test from test-scenarios.md
+
+## Terminal Discipline
+
+- **Timeout**: Every command gets one. Quick=15s, build=120s, test=300s. Default=30s.
+- **No foreground blockers**: `tail -f`, `watch`, dev servers → always `isBackground: true`.
+- **Output cap**: `| head -30` if output may exceed 50 lines.
+- **Stderr capture**: `2>&1 | head -N` for both stdout and stderr.
+- **No `cd &&` chaining**: Use `pushd path && command && popd` instead.
+- **Tools-first, terminal-last**: Never use terminal for tasks built-in tools handle (`Read`, `Grep`, `Glob`, `Write`).

package/assets/copilot/packs/frontend/skills/nextjs/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: nextjs
+description: NextJS development standards and best practices
+---
+# Next.js Best Practices for LLMs (2025)
+
+_Last updated: July 2025_
+
+This document summarizes the latest, authoritative best practices for building, structuring, and maintaining Next.js applications. It is intended for use by LLMs and developers to ensure code quality, maintainability, and scalability.
+ 
+
+## 1. Project Structure & Organization
+
+- **Use the `app/` directory** (App Router) for all new projects. Prefer it over the legacy `pages/` directory.
+- **Top-level folders:**
+  - `app/` — Routing, layouts, pages, and route handlers
+  - `public/` — Static assets (images, fonts, etc.)
+  - `lib/` — Shared utilities, API clients, and logic
+  - `components/` — Reusable UI components
+  - `contexts/` — React context providers
+  - `styles/` — Global and modular stylesheets
+  - `hooks/` — Custom React hooks
+  - `types/` — TypeScript type definitions
+- **Colocation:** Place files (components, styles, tests) near where they are used, but avoid deeply nested structures.
+- **Route Groups:** Use parentheses (e.g., `(admin)`) to group routes without affecting the URL path.
+- **Private Folders:** Prefix with `_` (e.g., `_internal`) to opt out of routing and signal implementation details.
+
+- **Feature Folders:** For large apps, group by feature (e.g., `app/dashboard/`, `app/auth/`).
+- **Use `src/`** (optional): Place all source code in `src/` to separate from config files.
+
+## 2.1. Server and Client Component Integration (App Router)
+
+**Never use `next/dynamic` with `{ ssr: false }` inside a Server Component.** This is not supported and will cause a build/runtime error.
+
+**Correct Approach:**
+
+- If you need to use a Client Component (e.g., a component that uses hooks, browser APIs, or client-only libraries) inside a Server Component, you must:
+  1. Move all client-only logic/UI into a dedicated Client Component (with `'use client'` at the top).
+  2. Import and use that Client Component directly in the Server Component (no need for `next/dynamic`).
+  3. If you need to compose multiple client-only elements (e.g., a navbar with a profile dropdown), create a single Client Component that contains all of them.
+
+**Example:**
+
+```tsx
+// Server Component
+import DashboardNavbar from '@/components/DashboardNavbar'
+
+export default async function DashboardPage() {
+  // ...server logic...
+  return (
+    <>
+      <DashboardNavbar /> {/* This is a Client Component */}
+      {/* ...rest of server-rendered page... */}
+    </>
+  )
+}
+```
+
+**Why:**
+
+- Server Components cannot use client-only features or dynamic imports with SSR disabled.
+- Client Components can be rendered inside Server Components, but not the other way around.
+
+**Summary:**
+Always move client-only UI into a Client Component and import it directly in your Server Component. Never use `next/dynamic` with `{ ssr: false }` in a Server Component.
+
+## 2.2. Data Fetching Strategy
+
+- **Real-time Lists**: For dynamic lists (users, properties, devices), prefer **Client-side Subscriptions** (SWR + Jotai) over Server Components fetching.
+  - **Why**: Enables real-time updates without page refreshes.
+  - **Pattern**: `page.tsx` (Server) -> `LayoutWrapper` (Client) -> `DataSubscriber` -> `Jotai Atom` -> `UI Component`.
+
+- **Static/SEO Content**: For public pages or static content, use **Server Components** with `await fetch()` or direct DB calls.
+
+- **Hybrid Approach**:
+  - Use Server Components for initial shell/layout.
+  - Use Client Components for the data-rich, interactive parts of the page.
+
+---
+
+## 2. Component Best Practices
+
+- **Component Types:**
+  - **Server Components** (default): For data fetching, heavy logic, and non-interactive UI.
+  - **Client Components:** Add `'use client'` at the top. Use for interactivity, state, or browser APIs.
+- **When to Create a Component:**
+  - If a UI pattern is reused more than once.
+  - If a section of a page is complex or self-contained.
+  - If it improves readability or testability.
+- **Naming Conventions:**
+  - Use `PascalCase` for component files and exports (e.g., `UserCard.tsx`).
+  - Use `camelCase` for hooks (e.g., `useUser.ts`).
+  - Use `snake_case` or `kebab-case` for static assets (e.g., `logo_dark.svg`).
+  - Name context providers as `XyzProvider` (e.g., `ThemeProvider`).
+- **File Naming:**
+  - Match the component name to the file name.
+  - For single-export files, default export the component.
+  - For multiple related components, use an `index.ts` barrel file.
+- **Component Location:**
+  - Place shared components in `components/`.
+  - Place route-specific components inside the relevant route folder.
+- **Props:**
+  - Use TypeScript interfaces for props.
+  - Prefer explicit prop types and default values.
+- **Testing:**
+  - Co-locate tests with components (e.g., `UserCard.test.tsx`).
+- **Icon Usage (Remix Icons):**
+  - Use **Remix Icons** (`ri-*` class prefix) for all action buttons and UI elements
+  - Do NOT use `tabler-*` icons in tables or action buttons (may not render correctly)
+  - Common patterns:
+    - Edit: `ri-edit-box-line`
+    - Delete: `ri-delete-bin-7-line`
+    - View: `ri-eye-line`
+    - Download: `ri-download-line`
+    - Add: `ri-add-line` or `tabler-plus` (tabler OK for non-table contexts)
+  - Apply `text-textSecondary` class for consistent styling in tables
+  - Example: `<i className='ri-edit-box-line text-textSecondary' />`
+
+## 3. Naming Conventions (General)
+
+- **Folders:** `kebab-case` (e.g., `user-profile/`)
+- **Files:** `PascalCase` for components, `camelCase` for utilities/hooks, `kebab-case` for static assets
+- **Variables/Functions:** `camelCase`
+- **Types/Interfaces:** `PascalCase`
+- **Constants:** `UPPER_SNAKE_CASE`
+
+## 4. API Routes (Route Handlers)
+
+- **Prefer API Routes over Edge Functions** unless you need ultra-low latency or geographic distribution.
+- **Location:** Place API routes in `app/api/` (e.g., `app/api/users/route.ts`).
+- **HTTP Methods:** Export async functions named after HTTP verbs (`GET`, `POST`, etc.).
+- **Request/Response:** Use the Web `Request` and `Response` APIs. Use `NextRequest`/`NextResponse` for advanced features.
+- **Dynamic Segments:** Use `[param]` for dynamic API routes (e.g., `app/api/users/[id]/route.ts`).
+- **Validation:** Always validate and sanitize input. Use libraries like `zod` or `yup`.
+- **Error Handling:** Return appropriate HTTP status codes and error messages.
+- **Authentication:** Protect sensitive routes using middleware or server-side session checks.
+
+## 5. General Best Practices
+
+- **TypeScript:** Use TypeScript for all code. Enable `strict` mode in `tsconfig.json`.
+- **ESLint & Prettier:** Enforce code style and linting. Use the official Next.js ESLint config.
+- **Environment Variables:** Store secrets in `.env.local`. Never commit secrets to version control.
+- **Testing:** Use Jest, React Testing Library, or Playwright. Write tests for all critical logic and components.
+- **Accessibility:** Use semantic HTML and ARIA attributes. Test with screen readers.
+- **Performance:**
+  - Use built-in Image and Font optimization.
+  - Use Suspense and loading states for async data.
+  - Avoid large client bundles; keep most logic in Server Components.
+- **Security:**
+  - Sanitize all user input.
+  - Use HTTPS in production.
+  - Set secure HTTP headers.
+- **Documentation:**
+  - Write clear README and code comments.
+  - Document public APIs and components.
+
+## 6. Type Definitions & Data Flow
+
+- **Single Type System:**
+  - Do NOT create separate "Serializable" types (e.g., `SerializableUser` vs `User`).
+  - Define base types with `string` for dates (ISO 8601 format) to ensure serializability across Server/Client boundaries.
+  - Example: `createdAt: string` instead of `createdAt: Date | Timestamp`.
+- **Data Transformation:**
+  - Transform database objects (e.g., Firestore Timestamps) to ISO strings immediately at the data fetching layer.
+  - Use helper functions (e.g., `transformFirestoreToUser`) to ensure consistent shaping.
+- **Strict Typing:**
+  - Avoid `any`. Use `unknown` if type is truly uncertain, then narrow.
+  - Share types between Server Actions and Client Components via `src/types/`.
+
+# Avoid Unnecessary Example Files
+
+Do not create example/demo files (like ModalExample.tsx) in the main codebase unless the user specifically requests a live example, Storybook story, or explicit documentation component. Keep the repository clean and production-focused by default.
+
+# Always use the latest documentation and guides
+
+- For every nextjs related request, begin by searching for the most current nextjs documentation, guides, and examples.
+- Use the following tools to fetch and search documentation if they are available:
+  - `resolve_library_id` to resolve the package/library name in the docs.
+  - `get_library_docs` for up to date documentation.

package/assets/copilot/packs/frontend/skills/nextjs-tailwind/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: nextjs-tailwind
+description: Next.js + Tailwind development standards and instructions. Use when working with TSX, TypeScript, JSX, JavaScript, or CSS files.
+---
+
+# Next.js + Tailwind Development Instructions
+
+Instructions for high-quality Next.js applications with Tailwind CSS styling and TypeScript.
+
+## Project Context
+
+- Latest Next.js (App Router)
+- TypeScript for type safety
+- Tailwind CSS for styling
+
+## Development Standards
+
+### Architecture
+- App Router with server and client components
+- Group routes by feature/domain
+- Implement proper error boundaries
+- Use React Server Components by default
+- Leverage static optimization where possible
+
+### TypeScript
+- Strict mode enabled
+- Clear type definitions
+- Proper error handling with type guards
+- Zod for runtime type validation
+
+### Styling
+- Tailwind CSS with consistent color palette
+- Responsive design patterns
+- Dark mode support
+- Follow container queries best practices
+- Maintain semantic HTML structure
+
+### State Management
+- React Server Components for server state
+- React hooks for client state
+- Proper loading and error states
+- Optimistic updates where appropriate
+
+### Data Fetching
+- Server Components for direct database queries
+- React Suspense for loading states
+- Proper error handling and retry logic
+- Cache invalidation strategies
+
+### Security
+- Input validation and sanitization
+- Proper authentication checks
+- CSRF protection
+- Rate limiting implementation
+- Secure API route handling
+
+### Performance
+- Image optimization with next/image
+- Font optimization with next/font
+- Route prefetching
+- Proper code splitting
+- Bundle size optimization
+
+## Implementation Process
+1. Plan component hierarchy
+2. Define types and interfaces
+3. Implement server-side logic
+4. Build client components
+5. Add proper error handling
+6. Implement responsive styling
+7. Add loading states
+8. Write tests