@qazuor/claude-code-config 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qazuor/claude-code-config",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI tool to install and manage Claude Code configurations",
   "type": "module",
   "bin": {
@@ -34,11 +34,11 @@
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "pnpm build && pnpm test:coverage",
     "ci": "pnpm lint && pnpm typecheck && pnpm test:coverage",
-    "release": "release-it",
-    "release:patch": "release-it patch",
-    "release:minor": "release-it minor",
-    "release:major": "release-it major",
-    "release:dry": "release-it --dry-run"
+    "release": "dotenv release-it",
+    "release:patch": "dotenv release-it patch",
+    "release:minor": "dotenv release-it minor",
+    "release:major": "dotenv release-it major",
+    "release:dry": "dotenv release-it --dry-run"
   },
   "dependencies": {
     "@inquirer/core": "^11.0.2",
@@ -61,6 +61,7 @@
     "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^2.1.8",
     "@vitest/ui": "^2.1.8",
+    "dotenv-cli": "^11.0.0",
     "memfs": "^4.14.1",
     "release-it": "^19.1.0",
     "tsup": "^8.3.5",

package/templates/docs/_registry.json

@@ -217,6 +217,60 @@
       "skillLevel": "advanced",
       "relatedModules": ["code-standards", "tech-lead", "product-technical"]
     },
+    {
+      "id": "design-standards",
+      "name": "Design Standards",
+      "description": "UI/UX design standards and accessibility guidelines",
+      "file": "standards/design-standards.md",
+      "tags": ["standards", "design", "ui", "ux", "accessibility"],
+      "longDescription": "Standards for UI/UX design including CSS framework usage, component library guidelines, accessibility requirements (WCAG), and dark mode support.",
+      "whatItDoes": [
+        "Defines CSS framework usage",
+        "Specifies component library standards",
+        "Sets accessibility requirements",
+        "Documents responsive design patterns",
+        "Guides dark mode implementation"
+      ],
+      "whenToUse": "When building or reviewing UI components. Ensures design consistency and accessibility.",
+      "skillLevel": "intermediate",
+      "relatedModules": ["code-standards", "ux-ui-designer"]
+    },
+    {
+      "id": "security-standards",
+      "name": "Security Standards",
+      "description": "Security best practices and authentication patterns",
+      "file": "standards/security-standards.md",
+      "tags": ["standards", "security", "authentication", "validation"],
+      "longDescription": "Security standards covering authentication patterns (JWT, OAuth), input validation, CSRF protection, rate limiting, and secure coding practices.",
+      "whatItDoes": [
+        "Defines authentication patterns",
+        "Specifies input validation requirements",
+        "Documents CSRF protection",
+        "Sets rate limiting guidelines",
+        "Guides secure coding practices"
+      ],
+      "whenToUse": "When implementing authentication, authorization, or handling user input.",
+      "skillLevel": "advanced",
+      "relatedModules": ["code-standards", "security-audit"]
+    },
+    {
+      "id": "performance-standards",
+      "name": "Performance Standards",
+      "description": "Performance targets and optimization guidelines",
+      "file": "standards/performance-standards.md",
+      "tags": ["standards", "performance", "optimization", "web-vitals"],
+      "longDescription": "Performance standards including Core Web Vitals targets (LCP, FID, CLS), bundle size limits, API response time requirements, and optimization best practices.",
+      "whatItDoes": [
+        "Sets Core Web Vitals targets",
+        "Defines bundle size limits",
+        "Specifies API response requirements",
+        "Documents caching strategies",
+        "Guides performance optimization"
+      ],
+      "whenToUse": "When optimizing performance or reviewing code for performance impact.",
+      "skillLevel": "advanced",
+      "relatedModules": ["code-standards", "performance-audit"]
+    },
     {
       "id": "pdr-template",
       "name": "PDR Template",

package/templates/docs/standards/code-standards.md

@@ -4,6 +4,26 @@ This document defines the coding standards. All code must follow these rules str
 
 ---
 
+## Configuration
+
+<!-- AUTO-GENERATED: Configured values -->
+| Setting | Value |
+|---------|-------|
+| **Indent Style** | {{INDENT_STYLE}} |
+| **Indent Size** | {{INDENT_SIZE}} |
+| **Max Line Length** | {{MAX_LINE_LENGTH}} |
+| **Max File Lines** | {{MAX_FILE_LINES}} |
+| **Quote Style** | {{QUOTE_STYLE}} |
+| **Semicolons** | {{USE_SEMICOLONS}} |
+| **Trailing Commas** | {{TRAILING_COMMAS}} |
+| **Allow any Type** | {{ALLOW_ANY}} |
+| **Named Exports Only** | {{NAMED_EXPORTS_ONLY}} |
+| **RO-RO Pattern** | {{RORO_PATTERN}} |
+| **JSDoc Required** | {{JSDOC_REQUIRED}} |
+<!-- END AUTO-GENERATED -->
+
+---
+
 ## Table of Contents
 
 <!-- markdownlint-disable MD051 -->

package/templates/docs/standards/design-standards.md

@@ -4,6 +4,19 @@
 
 This document defines the design system, ensuring visual consistency, accessibility, and maintainability across all applications (web, admin, and future mobile apps).
 
+---
+
+## Configuration
+
+<!-- AUTO-GENERATED: Configured values -->
+| Setting | Value |
+|---------|-------|
+| **CSS Framework** | {{CSS_FRAMEWORK}} |
+| **Component Library** | {{COMPONENT_LIBRARY}} |
+| **Accessibility Level** | WCAG {{ACCESSIBILITY_LEVEL}} |
+| **Dark Mode Support** | {{DARK_MODE_SUPPORT}} |
+<!-- END AUTO-GENERATED -->
+
 **Design System Stack:**
 
 - **Framework**: Tailwind CSS 4.x

package/templates/docs/standards/documentation-standards.md

@@ -4,6 +4,19 @@ This document defines the documentation standards.
 
 ---
 
+## Configuration
+
+<!-- AUTO-GENERATED: Configured values -->
+| Setting | Value |
+|---------|-------|
+| **JSDoc Level** | {{JSDOC_LEVEL}} |
+| **Require Examples** | {{REQUIRE_EXAMPLES}} |
+| **Changelog Format** | {{CHANGELOG_FORMAT}} |
+| **Inline Comment Policy** | {{INLINE_COMMENT_POLICY}} |
+<!-- END AUTO-GENERATED -->
+
+---
+
 ## Table of Contents
 
 <!-- markdownlint-disable MD051 -->

package/templates/docs/standards/performance-standards.md

@@ -0,0 +1,524 @@
+# Performance Standards
+
+This document defines the performance standards and targets for the project.
+
+---
+
+## Table of Contents
+
+<!-- markdownlint-disable MD051 -->
+
+1. [Performance Philosophy](#performance-philosophy)
+2. [Core Web Vitals](#core-web-vitals)
+3. [API Performance](#api-performance)
+4. [Bundle Size](#bundle-size)
+5. [Database Performance](#database-performance)
+6. [Caching Strategy](#caching-strategy)
+7. [Image Optimization](#image-optimization)
+8. [Monitoring](#monitoring)
+9. [Performance Checklist](#performance-checklist)
+
+<!-- markdownlint-enable MD051 -->
+
+---
+
+## Configuration
+
+<!-- AUTO-GENERATED: Configured values -->
+| Metric | Target |
+|--------|--------|
+| **LCP (Largest Contentful Paint)** | {{LCP_TARGET}}ms |
+| **FID (First Input Delay)** | {{FID_TARGET}}ms |
+| **CLS (Cumulative Layout Shift)** | {{CLS_TARGET}} |
+| **Initial Bundle Size** | {{BUNDLE_SIZE_TARGET}}KB |
+| **API Response Time** | {{API_RESPONSE_TARGET}}ms |
+<!-- END AUTO-GENERATED -->
+
+---
+
+## Performance Philosophy
+
+### Core Principles
+
+**Speed is a Feature:**
+
+- Performance directly impacts user experience
+- Slow sites lose users and revenue
+- Every millisecond matters
+
+**Measure, Don't Guess:**
+
+- Use real data from monitoring
+- Profile before optimizing
+- A/B test performance changes
+
+**Budget-Based Approach:**
+
+- Set performance budgets
+- Fail builds that exceed budgets
+- Track performance over time
+
+---
+
+## Core Web Vitals
+
+### LCP (Largest Contentful Paint)
+
+**Target: {{LCP_TARGET}}ms**
+
+LCP measures loading performance. It marks the time at which the largest content element becomes visible.
+
+**Optimization strategies:**
+
+```typescript
+// 1. Preload critical resources
+<link rel="preload" href="/hero-image.webp" as="image" />
+<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin />
+
+// 2. Use next/image for automatic optimization
+import Image from 'next/image';
+
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={600}
+  priority // Preloads the image
+  placeholder="blur"
+  blurDataURL={blurDataUrl}
+/>
+
+// 3. Server-side rendering for above-the-fold content
+export const getServerSideProps = async () => {
+  const heroData = await fetchHeroData();
+  return { props: { heroData } };
+};
+```
+
+**Common issues:**
+
+- Large images without optimization
+- Render-blocking CSS/JS
+- Slow server response time
+- Client-side rendering of critical content
+
+### FID (First Input Delay)
+
+**Target: {{FID_TARGET}}ms**
+
+FID measures interactivity. It measures the time from when a user first interacts with your page to when the browser responds.
+
+**Optimization strategies:**
+
+```typescript
+// 1. Split large JavaScript bundles
+const HeavyComponent = lazy(() => import('./HeavyComponent'));
+
+// 2. Use web workers for heavy computations
+const worker = new Worker('/workers/calculation.js');
+worker.postMessage({ data: largeDataset });
+worker.onmessage = (e) => setResult(e.data);
+
+// 3. Defer non-critical JavaScript
+<script src="/analytics.js" defer />
+
+// 4. Break up long tasks
+const processItems = async (items: Item[]) => {
+  for (const chunk of chunks(items, 100)) {
+    processChunk(chunk);
+    await new Promise(resolve => setTimeout(resolve, 0)); // Yield to main thread
+  }
+};
+```
+
+**Common issues:**
+
+- Large JavaScript bundles blocking main thread
+- Heavy computations on user interaction
+- Too many event listeners
+- Unoptimized third-party scripts
+
+### CLS (Cumulative Layout Shift)
+
+**Target: {{CLS_TARGET}}**
+
+CLS measures visual stability. It quantifies how often users experience unexpected layout shifts.
+
+**Optimization strategies:**
+
+```tsx
+// 1. Always set dimensions on images
+<Image
+  src="/photo.jpg"
+  alt="Photo"
+  width={400}
+  height={300}
+/>
+
+// 2. Reserve space for dynamic content
+<div className="min-h-[200px]">
+  {isLoading ? <Skeleton /> : <Content />}
+</div>
+
+// 3. Use CSS aspect-ratio
+.video-container {
+  aspect-ratio: 16 / 9;
+}
+
+// 4. Font loading strategy
+<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin />
+
+// In CSS:
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/inter.woff2') format('woff2');
+  font-display: swap; // or 'optional' for less CLS
+}
+```
+
+**Common issues:**
+
+- Images without dimensions
+- Ads or embeds without reserved space
+- Dynamically injected content
+- Web fonts causing FOIT/FOUT
+
+---
+
+## API Performance
+
+### Response Time Target: {{API_RESPONSE_TARGET}}ms
+
+**Optimization strategies:**
+
+```typescript
+// 1. Database query optimization
+// Bad: N+1 queries
+const users = await db.query.users.findMany();
+for (const user of users) {
+  const bookings = await db.query.bookings.findMany({
+    where: eq(bookings.userId, user.id),
+  });
+}
+
+// Good: Single query with join
+const usersWithBookings = await db.query.users.findMany({
+  with: {
+    bookings: true,
+  },
+});
+
+// 2. Pagination for large datasets
+const findAll = async ({ page = 1, pageSize = 20 }: PaginationInput) => {
+  const [items, total] = await Promise.all([
+    db.query.entities.findMany({
+      limit: pageSize,
+      offset: (page - 1) * pageSize,
+    }),
+    db.select({ count: count() }).from(entities),
+  ]);
+
+  return { items, total: total[0].count };
+};
+
+// 3. Response compression
+import { compress } from 'hono/compress';
+app.use('*', compress());
+
+// 4. Parallel requests when possible
+const [user, bookings, reviews] = await Promise.all([
+  fetchUser(userId),
+  fetchBookings(userId),
+  fetchReviews(userId),
+]);
+```
+
+### API Performance Budgets
+
+| Operation | Target | Maximum |
+|-----------|--------|---------|
+| Simple GET | <50ms | <100ms |
+| List with pagination | <100ms | <200ms |
+| Create/Update | <150ms | <300ms |
+| Complex queries | <200ms | <500ms |
+| Bulk operations | <500ms | <1000ms |
+
+---
+
+## Bundle Size
+
+### Target: {{BUNDLE_SIZE_TARGET}}KB (initial)
+
+**Analysis tools:**
+
+```bash
+# Analyze bundle size
+pnpm build --analyze
+
+# Using next-bundle-analyzer
+ANALYZE=true pnpm build
+```
+
+**Optimization strategies:**
+
+```typescript
+// 1. Dynamic imports for route-based code splitting
+const AdminDashboard = lazy(() => import('./AdminDashboard'));
+
+// 2. Tree shaking - use named imports
+// Bad
+import _ from 'lodash';
+// Good
+import { debounce } from 'lodash-es';
+
+// 3. Replace heavy libraries
+// Instead of moment.js (300KB)
+import { format, parseISO } from 'date-fns'; // 12KB
+
+// Instead of lodash (70KB)
+// Use native methods or lodash-es with tree shaking
+
+// 4. External dependencies for SSR
+// next.config.js
+module.exports = {
+  experimental: {
+    serverComponentsExternalPackages: ['sharp', 'canvas'],
+  },
+};
+```
+
+### Bundle Size Budgets
+
+| Category | Budget |
+|----------|--------|
+| Main JS bundle | <100KB gzipped |
+| Route-specific JS | <50KB gzipped |
+| CSS total | <50KB gzipped |
+| Images above fold | <200KB |
+| Total page weight | <500KB |
+
+---
+
+## Database Performance
+
+### Query Optimization
+
+```typescript
+// 1. Use indexes for frequently queried columns
+// In migration:
+export const entitiesTable = pgTable('entities', {
+  id: uuid('id').primaryKey(),
+  hostId: uuid('host_id').notNull(),
+  type: varchar('type', { length: 50 }).notNull(),
+  createdAt: timestamp('created_at').defaultNow(),
+}, (table) => ({
+  hostIdIdx: index('entities_host_id_idx').on(table.hostId),
+  typeIdx: index('entities_type_idx').on(table.type),
+  createdAtIdx: index('entities_created_at_idx').on(table.createdAt),
+}));
+
+// 2. Select only needed columns
+const entities = await db.query.entities.findMany({
+  columns: {
+    id: true,
+    name: true,
+    type: true,
+    pricePerNight: true,
+    // Don't select large columns like 'description' if not needed
+  },
+});
+
+// 3. Use explain to analyze queries
+const result = await db.execute(sql`
+  EXPLAIN ANALYZE
+  SELECT * FROM entities
+  WHERE type = ${type}
+  ORDER BY created_at DESC
+  LIMIT 20
+`);
+```
+
+### Connection Pooling
+
+```typescript
+// Configure connection pool
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,              // Max connections
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+```
+
+---
+
+## Caching Strategy
+
+### Multi-Layer Caching
+
+```typescript
+// 1. In-memory cache for hot data
+import { LRUCache } from 'lru-cache';
+
+const cache = new LRUCache<string, unknown>({
+  max: 500,
+  ttl: 1000 * 60 * 5, // 5 minutes
+});
+
+// 2. Redis for distributed cache
+import { Redis } from '@upstash/redis';
+
+const redis = Redis.fromEnv();
+
+const getCached = async <T>(key: string, fetcher: () => Promise<T>, ttl = 300): Promise<T> => {
+  const cached = await redis.get<T>(key);
+  if (cached) return cached;
+
+  const data = await fetcher();
+  await redis.setex(key, ttl, data);
+  return data;
+};
+
+// 3. HTTP caching headers
+const setCacheHeaders = (c: Context, maxAge: number) => {
+  c.header('Cache-Control', `public, max-age=${maxAge}, s-maxage=${maxAge * 2}`);
+  c.header('CDN-Cache-Control', `public, max-age=${maxAge * 2}`);
+};
+```
+
+### Cache Invalidation
+
+```typescript
+// Invalidate on mutation
+const updateEntity = async (id: string, data: UpdateEntityInput) => {
+  await db.update(entities).set(data).where(eq(entities.id, id));
+
+  // Invalidate caches
+  await redis.del(`entity:${id}`);
+  await redis.del(`entities:list:*`); // Pattern delete
+};
+```
+
+---
+
+## Image Optimization
+
+### Image Guidelines
+
+```typescript
+// Use next/image or similar
+import Image from 'next/image';
+
+<Image
+  src={entity.image}
+  alt={entity.name}
+  width={800}
+  height={600}
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  loading="lazy" // or "eager" for above-fold
+  placeholder="blur"
+/>
+```
+
+### Image Formats
+
+| Format | Use Case |
+|--------|----------|
+| WebP | Primary format (30% smaller than JPEG) |
+| AVIF | Modern browsers (50% smaller) |
+| JPEG | Fallback for older browsers |
+| PNG | Graphics with transparency |
+| SVG | Icons and logos |
+
+### Image Sizes
+
+| Use Case | Max Width | Quality |
+|----------|-----------|---------|
+| Thumbnail | 200px | 80% |
+| Card image | 400px | 80% |
+| Hero image | 1200px | 85% |
+| Full width | 1920px | 85% |
+
+---
+
+## Monitoring
+
+### Performance Monitoring Setup
+
+```typescript
+// Using Web Vitals
+import { onCLS, onFID, onLCP, onFCP, onTTFB } from 'web-vitals';
+
+const sendToAnalytics = (metric: Metric) => {
+  // Send to your analytics service
+  fetch('/api/metrics', {
+    method: 'POST',
+    body: JSON.stringify(metric),
+  });
+};
+
+onCLS(sendToAnalytics);
+onFID(sendToAnalytics);
+onLCP(sendToAnalytics);
+onFCP(sendToAnalytics);
+onTTFB(sendToAnalytics);
+```
+
+### Server-Side Monitoring
+
+```typescript
+// Track API response times
+const timingMiddleware = async (c: Context, next: Next) => {
+  const start = performance.now();
+
+  await next();
+
+  const duration = performance.now() - start;
+  c.header('Server-Timing', `total;dur=${duration.toFixed(2)}`);
+
+  // Log slow requests
+  if (duration > {{API_RESPONSE_TARGET}}) {
+    console.warn(`Slow request: ${c.req.path} took ${duration}ms`);
+  }
+};
+```
+
+---
+
+## Performance Checklist
+
+Before deploying:
+
+**Core Web Vitals:**
+
+- [ ] LCP < {{LCP_TARGET}}ms
+- [ ] FID < {{FID_TARGET}}ms
+- [ ] CLS < {{CLS_TARGET}}
+
+**Frontend:**
+
+- [ ] Initial bundle < {{BUNDLE_SIZE_TARGET}}KB
+- [ ] Images optimized (WebP, proper sizing)
+- [ ] Critical CSS inlined
+- [ ] Fonts preloaded
+- [ ] Lazy loading for below-fold content
+
+**Backend:**
+
+- [ ] API responses < {{API_RESPONSE_TARGET}}ms
+- [ ] Database queries optimized
+- [ ] Caching implemented
+- [ ] Response compression enabled
+
+**Monitoring:**
+
+- [ ] Web Vitals tracking enabled
+- [ ] API performance monitoring
+- [ ] Error tracking configured
+- [ ] Alerts for performance regressions
+
+---
+
+**Performance is a feature. All code must meet these standards.**