@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/copilot/instructions-extended/reactjs/reactjs.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'ReactJS development standards and best practices. Use when working with JSX, TSX, JavaScript, TypeScript, CSS, or SCSS files.'
+applyTo: '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss'
+---
+
+# ReactJS Development Instructions
+
+Instructions for building high-quality ReactJS applications with modern patterns, hooks, and best practices following the official React documentation at https://react.dev.
+
+## Project Context
+- Latest React version (React 19+)
+- TypeScript for type safety (when applicable)
+- Functional components with hooks as default
+- Follow React's official style guide and best practices
+- Use modern build tools (Vite, Create React App, or custom Webpack setup)
+- Implement proper component composition and reusability patterns
+
+## Development Standards
+
+### Architecture
+- Use functional components with hooks as the primary pattern
+- Implement component composition over inheritance
+- Organize components by feature or domain for scalability
+- Separate presentational and container components clearly
+- Use custom hooks for reusable stateful logic
+- Implement proper component hierarchies with clear data flow
+
+### TypeScript Integration
+- Use TypeScript interfaces for props, state, and component definitions
+- Define proper types for event handlers and refs
+- Implement generic components where appropriate
+- Use strict mode in `tsconfig.json` for type safety
+- Leverage React's built-in types (`React.FC`, `React.ComponentProps`, etc.)
+- Create union types for component variants and states
+
+### Component Design
+- Follow the single responsibility principle for components
+- Use descriptive and consistent naming conventions
+- Implement proper prop validation with TypeScript or PropTypes
+- Design components to be testable and reusable
+- Keep components small and focused on a single concern
+- Use composition patterns (render props, children as functions)
+
+### State Management
+- Use `useState` for local component state
+- Implement `useReducer` for complex state logic
+- Leverage `useContext` for sharing state across component trees
+- Consider external state management (Redux Toolkit, Zustand) for complex applications
+- Implement proper state normalization and data structures
+- Use React Query or SWR for server state management
+
+### Hooks and Effects
+- Use `useEffect` with proper dependency arrays to avoid infinite loops
+- Implement cleanup functions in effects to prevent memory leaks
+- Use `useMemo` and `useCallback` for performance optimization when needed
+- Create custom hooks for reusable stateful logic
+- Follow the rules of hooks (only call at the top level)
+- Use `useRef` for accessing DOM elements and storing mutable values
+
+### Styling
+- Use CSS Modules, Styled Components, or modern CSS-in-JS solutions
+- Implement responsive design with mobile-first approach
+- Follow BEM methodology or similar naming conventions for CSS classes
+- Use CSS custom properties (variables) for theming
+- Implement consistent spacing, typography, and color systems
+- Ensure accessibility with proper ARIA attributes and semantic HTML
+
+### Performance Optimization
+- Use `React.memo` for component memoization when appropriate
+- Implement code splitting with `React.lazy` and `Suspense`
+- Optimize bundle size with tree shaking and dynamic imports
+- Use `useMemo` and `useCallback` judiciously to prevent unnecessary re-renders
+- Implement virtual scrolling for large lists
+- Profile components with React DevTools to identify performance bottlenecks
+
+### Data Fetching
+- Use modern data fetching libraries (React Query, SWR, Apollo Client)
+- Implement proper loading, error, and success states
+- Handle race conditions and request cancellation
+- Use optimistic updates for better user experience
+- Implement proper caching strategies
+- Handle offline scenarios and network errors gracefully
+
+### Error Handling
+- Implement Error Boundaries for component-level error handling
+- Use proper error states in data fetching
+- Implement fallback UI for error scenarios
+- Log errors appropriately for debugging
+- Handle async errors in effects and event handlers
+- Provide meaningful error messages to users
+
+### Forms and Validation
+- Use controlled components for form inputs
+- Implement proper form validation with libraries like Formik, React Hook Form
+- Handle form submission and error states appropriately
+- Implement accessibility features for forms (labels, ARIA attributes)
+- Use debounced validation for better user experience
+- Handle file uploads and complex form scenarios
+
+### Routing
+- Use React Router for client-side routing
+- Implement nested routes and route protection
+- Handle route parameters and query strings properly
+- Implement lazy loading for route-based code splitting
+- Use proper navigation patterns and back button handling
+- Implement breadcrumbs and navigation state management
+
+### Testing
+- Write unit tests for components using React Testing Library
+- Test component behavior, not implementation details
+- Use Jest for test runner and assertion library
+- Implement integration tests for complex component interactions
+- Mock external dependencies and API calls appropriately
+- Test accessibility features and keyboard navigation
+
+### Security
+- Sanitize user inputs to prevent XSS attacks
+- Validate and escape data before rendering
+- Use HTTPS for all external API calls
+- Implement proper authentication and authorization patterns
+- Avoid storing sensitive data in localStorage or sessionStorage
+- Use Content Security Policy (CSP) headers
+
+### Accessibility
+- Use semantic HTML elements appropriately
+- Implement proper ARIA attributes and roles
+- Ensure keyboard navigation works for all interactive elements
+- Provide alt text for images and descriptive text for icons
+- Implement proper color contrast ratios
+- Test with screen readers and accessibility tools
+
+## Implementation Process
+1. Plan component architecture and data flow
+2. Set up project structure with proper folder organization
+3. Define TypeScript interfaces and types
+4. Implement core components with proper styling
+5. Add state management and data fetching logic
+6. Implement routing and navigation
+7. Add form handling and validation
+8. Implement error handling and loading states
+9. Add testing coverage for components and functionality
+10. Optimize performance and bundle size
+11. Ensure accessibility compliance
+12. Add documentation and code comments
+
+## Additional Guidelines
+- Follow React's naming conventions (PascalCase for components, camelCase for functions)
+- Use meaningful commit messages and maintain clean git history
+- Implement proper code splitting and lazy loading strategies
+- Document complex components and custom hooks with JSDoc
+- Use ESLint and Prettier for consistent code formatting
+- Keep dependencies up to date and audit for security vulnerabilities
+- Implement proper environment configuration for different deployment stages
+- Use React Developer Tools for debugging and performance analysis
+
+## Common Patterns
+- Higher-Order Components (HOCs) for cross-cutting concerns
+- Render props pattern for component composition
+- Compound components for related functionality
+- Provider pattern for context-based state sharing
+- Container/Presentational component separation
+- Custom hooks for reusable logic extraction

package/assets/copilot/instructions-extended/self-explanatory-code-commenting/self-explanatory-code-commenting.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'Conventions for writing and reviewing code comments: prefer self-explanatory code, comment WHY not WHAT, and avoid obvious, redundant, outdated, dead-code, or decorative comments. Language-agnostic (examples in JavaScript). Use when working with Python, JavaScript, TypeScript, Java, C#, C++, Go, or Ruby files.'
+applyTo: '**/*.py, **/*.js, **/*.ts, **/*.java, **/*.cs, **/*.cpp, **/*.go, **/*.rb'
+---
+
+# Self-explanatory Code Commenting Instructions
+
+## Core Principle
+**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**
+We do not need comments most of the time.
+
+## Commenting Guidelines
+
+### ❌ AVOID These Comment Types
+
+**Obvious Comments**
+```javascript
+// Bad: States the obvious
+let counter = 0;  // Initialize counter to zero
+counter++;  // Increment counter by one
+```
+
+**Redundant Comments**
+```javascript
+// Bad: Comment repeats the code
+function getUserName() {
+    return user.name;  // Return the user's name
+}
+```
+
+**Outdated Comments**
+```javascript
+// Bad: Comment doesn't match the code
+// Calculate tax at 5% rate
+const tax = price * 0.08;  // Actually 8%
+```
+
+### ✅ WRITE These Comment Types
+
+**Complex Business Logic**
+```javascript
+// Good: Explains WHY this specific calculation
+// Apply progressive tax brackets: 10% up to 10k, 20% above
+const tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);
+```
+
+**Non-obvious Algorithms**
+```javascript
+// Good: Explains the algorithm choice
+// Using Floyd-Warshall for all-pairs shortest paths
+// because we need distances between all nodes
+for (let k = 0; k < vertices; k++) {
+    for (let i = 0; i < vertices; i++) {
+        for (let j = 0; j < vertices; j++) {
+            // ... implementation
+        }
+    }
+}
+```
+
+**Regex Patterns**
+```javascript
+// Good: Explains what the regex matches
+// Match email format: username@domain.extension
+const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+```
+
+**API Constraints or Gotchas**
+```javascript
+// Good: Explains external constraint
+// GitHub API rate limit: 5000 requests/hour for authenticated users
+await rateLimiter.wait();
+const response = await fetch(githubApiUrl);
+```
+
+## Decision Framework
+
+Before writing a comment, ask:
+1. **Is the code self-explanatory?** → No comment needed
+2. **Would a better variable/function name eliminate the need?** → Refactor instead
+3. **Does this explain WHY, not WHAT?** → Good comment
+4. **Will this help future maintainers?** → Good comment
+
+## Special Cases for Comments
+
+### Public APIs
+```javascript
+/**
+ * Calculate compound interest using the standard formula.
+ * 
+ * @param {number} principal - Initial amount invested
+ * @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
+ * @param {number} time - Time period in years
+ * @param {number} compoundFrequency - How many times per year interest compounds (default: 1)
+ * @returns {number} Final amount after compound interest
+ */
+function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
+    // ... implementation
+}
+```
+
+### Configuration and Constants
+```javascript
+// Good: Explains the source or reasoning
+const MAX_RETRIES = 3;  // Based on network reliability studies
+const API_TIMEOUT = 5000;  // AWS Lambda timeout is 15s, leaving buffer
+```
+
+### Annotations
+```javascript
+// TODO: Replace with proper user authentication after security review
+// FIXME: Memory leak in production - investigate connection pooling
+// HACK: Workaround for bug in library v2.1.0 - remove after upgrade
+// NOTE: This implementation assumes UTC timezone for all calculations
+// WARNING: This function modifies the original array instead of creating a copy
+// PERF: Consider caching this result if called frequently in hot path
+// SECURITY: Validate input to prevent SQL injection before using in query
+// BUG: Edge case failure when array is empty - needs investigation
+// REFACTOR: Extract this logic into separate utility function for reusability
+// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0
+```
+
+## Anti-Patterns to Avoid
+
+### Dead Code Comments
+```javascript
+// Bad: Don't comment out code
+// const oldFunction = () => { ... };
+const newFunction = () => { ... };
+```
+
+### Changelog Comments
+```javascript
+// Bad: Don't maintain history in comments
+// Modified by John on 2023-01-15
+// Fixed bug reported by Sarah on 2023-02-03
+function processData() {
+    // ... implementation
+}
+```
+
+### Divider Comments
+```javascript
+// Bad: Don't use decorative comments
+//=====================================
+// UTILITY FUNCTIONS
+//=====================================
+```
+
+## Quality Checklist
+
+Before committing, ensure your comments:
+- [ ] Explain WHY, not WHAT
+- [ ] Are grammatically correct and clear
+- [ ] Will remain accurate as code evolves
+- [ ] Add genuine value to code understanding
+- [ ] Are placed appropriately (above the code they describe)
+- [ ] Use proper spelling and professional language
+
+## Summary
+
+Remember: **The best comment is the one you don't need to write because the code is self-documenting.**

package/assets/copilot/instructions-extended/tailwind-v4-vite/tailwind-v4-vite.instructions.md

@@ -0,0 +1,236 @@
+---
+description: 'Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin. Use when working with TypeScript, JavaScript, CSS, TSX, or JSX files.'
+applyTo: 'vite.config.ts, vite.config.js, **/*.css, **/*.tsx, **/*.ts, **/*.jsx, **/*.js'
+---
+
+# Tailwind CSS v4+ Installation with Vite
+
+Instructions for installing and configuring Tailwind CSS version 4 and above using the official Vite plugin. Tailwind CSS v4 introduces a simplified setup that eliminates the need for PostCSS configuration and tailwind.config.js in most cases.
+
+## Key Changes in Tailwind CSS v4
+
+- **No PostCSS configuration required** when using the Vite plugin
+- **No tailwind.config.js required** - configuration is done via CSS
+- **New @tailwindcss/vite plugin** replaces the PostCSS-based approach
+- **CSS-first configuration** using `@theme` directive
+- **Automatic content detection** - no need to specify content paths
+
+## Installation Steps
+
+### Step 1: Install Dependencies
+
+Install `tailwindcss` and the `@tailwindcss/vite` plugin:
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+### Step 2: Configure Vite Plugin
+
+Add the `@tailwindcss/vite` plugin to your Vite configuration file:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+	plugins: [tailwindcss()],
+});
+```
+
+For React projects with Vite:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+	plugins: [react(), tailwindcss()],
+});
+```
+
+### Step 3: Import Tailwind CSS
+
+Add the Tailwind CSS import to your main CSS file (e.g., `src/index.css` or `src/App.css`):
+
+```css
+@import 'tailwindcss';
+```
+
+### Step 4: Verify CSS Import in Entry Point
+
+Ensure your main CSS file is imported in your application entry point:
+
+```typescript
+// src/main.tsx or src/main.ts
+import './index.css';
+```
+
+### Step 5: Start Development Server
+
+Run the development server to verify installation:
+
+```bash
+npm run dev
+```
+
+## What NOT to Do in Tailwind v4
+
+### Do NOT Create tailwind.config.js
+
+Tailwind v4 uses CSS-first configuration. Do not create a `tailwind.config.js` file unless you have specific legacy requirements.
+
+```javascript
+// ❌ NOT NEEDED in Tailwind v4
+module.exports = {
+	content: ['./src/**/*.{js,ts,jsx,tsx}'],
+	theme: {
+		extend: {},
+	},
+	plugins: [],
+};
+```
+
+### Do NOT Create postcss.config.js for Tailwind
+
+When using the `@tailwindcss/vite` plugin, PostCSS configuration for Tailwind is not required.
+
+```javascript
+// ❌ NOT NEEDED when using @tailwindcss/vite
+module.exports = {
+	plugins: {
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};
+```
+
+### Do NOT Use Old Directives
+
+The old `@tailwind` directives are replaced by a single import:
+
+```css
+/* ❌ OLD - Do not use in Tailwind v4 */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ✅ NEW - Use this in Tailwind v4 */
+@import 'tailwindcss';
+```
+
+## CSS-First Configuration (Tailwind v4)
+
+### Custom Theme Configuration
+
+Use the `@theme` directive in your CSS to customize your design tokens:
+
+```css
+@import 'tailwindcss';
+
+@theme {
+	--color-primary: #3b82f6;
+	--color-secondary: #64748b;
+	--font-sans: 'Inter', system-ui, sans-serif;
+	--radius-lg: 0.75rem;
+}
+```
+
+### Adding Custom Utilities
+
+Define custom utilities directly in CSS:
+
+```css
+@import 'tailwindcss';
+
+@utility content-auto {
+	content-visibility: auto;
+}
+
+@utility scrollbar-hidden {
+	scrollbar-width: none;
+	&::-webkit-scrollbar {
+		display: none;
+	}
+}
+```
+
+### Adding Custom Variants
+
+Define custom variants in CSS:
+
+```css
+@import 'tailwindcss';
+
+@variant hocus (&:hover, &:focus);
+@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);
+```
+
+## Verification Checklist
+
+After installation, verify:
+
+- [ ] `tailwindcss` and `@tailwindcss/vite` are in `package.json` dependencies
+- [ ] `vite.config.ts` includes the `tailwindcss()` plugin
+- [ ] Main CSS file contains `@import "tailwindcss";`
+- [ ] CSS file is imported in the application entry point
+- [ ] Development server runs without errors
+- [ ] Tailwind utility classes (e.g., `text-blue-500`, `p-4`) render correctly
+
+## Example Usage
+
+Test the installation with a simple component:
+
+```tsx
+export function TestComponent() {
+	return (
+		<div className='min-h-screen bg-gray-100 flex items-center justify-center'>
+			<h1 className='text-3xl font-bold text-blue-600 underline'>Hello, Tailwind CSS v4!</h1>
+		</div>
+	);
+}
+```
+
+## Troubleshooting
+
+### Styles Not Applying
+
+1. Verify CSS import statement is `@import "tailwindcss";` (not old directives)
+2. Ensure CSS file is imported in your entry point
+3. Check Vite config includes the `tailwindcss()` plugin
+4. Clear Vite cache: `rm -rf node_modules/.vite && npm run dev`
+
+### Plugin Not Found Error
+
+If you see "Cannot find module '@tailwindcss/vite'":
+
+```bash
+npm install @tailwindcss/vite
+```
+
+### TypeScript Errors
+
+If TypeScript cannot find types for the Vite plugin, ensure you have the correct import:
+
+```typescript
+import tailwindcss from '@tailwindcss/vite';
+```
+
+## Migration from Tailwind v3
+
+If migrating from Tailwind v3:
+
+1. Remove `tailwind.config.js` (move customizations to CSS `@theme`)
+2. Remove `postcss.config.js` (if only used for Tailwind)
+3. Uninstall old packages: `npm uninstall postcss autoprefixer`
+4. Install new packages: `npm install tailwindcss @tailwindcss/vite`
+5. Replace `@tailwind` directives with `@import "tailwindcss";`
+6. Update Vite config to use `@tailwindcss/vite` plugin
+
+## Reference
+
+- Official Documentation: https://tailwindcss.com/docs/installation/using-vite
+- Tailwind CSS v4 Upgrade Guide: https://tailwindcss.com/docs/upgrade-guide