@windagency/valora 2.0.1

package/data/templates/plans/PATTERN_REST_API.md

@@ -0,0 +1,428 @@
+---
+pattern: rest-api
+complexity_range: 2-5
+estimated_time: '3-5 minutes'
+use_when:
+  - Adding new API endpoints
+  - CRUD operations
+  - RESTful resources
+  - HTTP handlers
+applies_to:
+  - Node.js/Express
+  - TypeScript
+  - REST APIs
+---
+
+# REST API Implementation Plan Template
+
+**Pattern**: REST API Endpoint
+**Typical Complexity**: 2-5/10
+**Standard Planning Time**: 3-5 minutes (vs 13-15 min for full analysis)
+
+## TASK OVERVIEW
+
+**Summary**: Add RESTful API endpoint(s) for [RESOURCE_NAME]
+
+**Scope**:
+
+- HTTP endpoints: [LIST_ENDPOINTS]
+- Request/response handling
+- Input validation
+- Error handling
+- Database operations (if applicable)
+
+**Success Criteria**:
+
+- [ ] Endpoints return correct HTTP status codes
+- [ ] Input validation rejects invalid requests
+- [ ] Responses match OpenAPI schema
+- [ ] Error messages are descriptive
+- [ ] Unit and integration tests pass
+
+## COMPLEXITY ASSESSMENT
+
+**Score**: [AUTO_CALCULATED: 2-5/10]
+
+**Breakdown**:
+
+- Code Volume: 3/10 (~150-300 lines)
+- Component Coupling: 2/10 (controller + service + repository)
+- Data Complexity: [2-5]/10 (depends on schema changes)
+- Integration: 2/10 (standard database only)
+- Business Logic: [2-5]/10 (depends on requirements)
+- Testing: 4/10 (unit + integration tests)
+- Risk Level: 3/10 (isolated, backward compatible)
+
+**Mode**: Standard (single-pass implementation)
+
+## DEPENDENCIES
+
+### Technical Dependencies
+
+- ✅ Express (already installed)
+- ✅ Zod (input validation - already installed)
+- ✅ TypeScript (already configured)
+- [ADD_DATABASE_LIB if needed, e.g., Prisma, TypeORM]
+
+### Data Dependencies
+
+- [LIST_TABLES_REQUIRED]
+- [LIST_SCHEMA_CHANGES if adding columns/tables]
+
+### Integration Dependencies
+
+- Database connection (already configured)
+- [ADD_EXTERNAL_SERVICES if applicable]
+
+**Execution Order**:
+
+1. Schema/migration (if database changes)
+2. Types and validation schemas
+3. Repository/database layer
+4. Service layer (business logic)
+5. Controller/route handler
+6. Tests
+
+## RISK ASSESSMENT
+
+### Technical Risks
+
+**RISK-001: Input validation bypass**
+
+- **Severity**: Medium
+- **Likelihood**: Low
+- **Mitigation**:
+  - Use Zod schema validation on all inputs
+  - Validate at controller layer before business logic
+  - Add integration tests for invalid inputs
+  - Test SQL injection, XSS payloads
+
+**RISK-002: Database query performance**
+
+- **Severity**: Medium
+- **Likelihood**: Medium (if complex queries)
+- **Mitigation**:
+  - Add database indexes for query filters
+  - Use pagination for list endpoints (limit/offset)
+  - Test with realistic data volumes
+  - Monitor query execution times
+
+**RISK-003: Breaking changes to existing clients**
+
+- **Severity**: High (if modifying existing endpoints)
+- **Likelihood**: Low (new endpoints)
+- **Mitigation**:
+  - Version API endpoints (e.g., /api/v1/resource)
+  - Maintain backward compatibility
+  - Add deprecation warnings if changing existing endpoints
+  - Update API documentation
+
+### Business Risks
+
+**RISK-004: Authorization gaps**
+
+- **Severity**: High
+- **Likelihood**: Medium
+- **Mitigation**:
+  - Apply authentication middleware to all endpoints
+  - Implement role-based access control (RBAC)
+  - Test unauthorized access scenarios
+  - Log all access attempts
+
+### Operational Risks
+
+**RISK-005: Deployment rollback difficulty**
+
+- **Severity**: Low
+- **Likelihood**: Low
+- **Mitigation**:
+  - Feature flag for new endpoints
+  - Database migrations are reversible
+  - Rollback plan documented
+
+## IMPLEMENTATION STEPS
+
+### Step 1: Define Types and Schemas [15 min]
+
+**File**: `src/types/[resource].types.ts`
+
+**Actions**:
+
+- Create TypeScript interfaces for request/response
+- Define Zod validation schemas
+- Export types for reuse
+
+**Validation**:
+
+- Types compile without errors
+- Zod schemas validate expected inputs
+
+**Example**:
+
+```typescript
+// src/types/user.types.ts
+import { z } from 'zod';
+
+export const CreateUserSchema = z.object({
+	email: z.string().email(),
+	name: z.string().min(1).max(100)
+});
+
+export type CreateUserRequest = z.infer<typeof CreateUserSchema>;
+export interface UserResponse {
+	id: string;
+	email: string;
+	name: string;
+	createdAt: string;
+}
+```
+
+### Step 2: Create Database Repository [20 min]
+
+**File**: `src/repositories/[resource].repository.ts`
+
+**Actions**:
+
+- Implement CRUD methods (create, read, update, delete)
+- Use parameterized queries to prevent SQL injection
+- Handle database errors gracefully
+
+**Validation**:
+
+- Repository unit tests pass
+- Database operations work correctly
+
+**Example**:
+
+```typescript
+// src/repositories/user.repository.ts
+export class UserRepository {
+	async create(data: CreateUserRequest): Promise<User> {
+		return await prisma.user.create({ data });
+	}
+
+	async findById(id: string): Promise<User | null> {
+		return await prisma.user.findUnique({ where: { id } });
+	}
+}
+```
+
+### Step 3: Implement Service Layer [20 min]
+
+**File**: `src/services/[resource].service.ts`
+
+**Actions**:
+
+- Add business logic
+- Call repository methods
+- Handle errors and edge cases
+- Return structured responses
+
+**Validation**:
+
+- Service unit tests pass
+- Business logic is correct
+
+### Step 4: Create Route Handlers [25 min]
+
+**File**: `src/routes/[resource].routes.ts`
+
+**Actions**:
+
+- Define Express routes (GET, POST, PUT, DELETE)
+- Apply validation middleware
+- Apply authentication middleware
+- Call service layer
+- Return HTTP responses with correct status codes
+
+**Validation**:
+
+- Routes registered correctly
+- Middleware applied in correct order
+- Handler integration tests pass
+
+**HTTP Status Codes**:
+
+- 200 OK (GET success)
+- 201 Created (POST success)
+- 204 No Content (DELETE success)
+- 400 Bad Request (validation error)
+- 401 Unauthorized (missing auth)
+- 403 Forbidden (insufficient permissions)
+- 404 Not Found (resource not found)
+- 500 Internal Server Error (unexpected errors)
+
+### Step 5: Add Error Handling [15 min]
+
+**File**: `src/middleware/error-handler.ts`
+
+**Actions**:
+
+- Centralized error handling middleware
+- Return consistent error response format
+- Log errors for monitoring
+
+**Validation**:
+
+- Error responses match expected format
+- Sensitive information not leaked
+
+### Step 6: Write Tests [30 min]
+
+**Files**:
+
+- `tests/unit/services/[resource].service.test.ts`
+- `tests/integration/routes/[resource].routes.test.ts`
+
+**Test Cases**:
+
+- **Unit Tests**:
+  - Service methods handle valid inputs
+  - Service methods reject invalid inputs
+  - Service methods handle database errors
+
+- **Integration Tests**:
+  - POST /[resource] creates resource
+  - GET /[resource]/:id returns resource
+  - PUT /[resource]/:id updates resource
+  - DELETE /[resource]/:id deletes resource
+  - Invalid requests return 400
+  - Unauthorized requests return 401
+  - Not found requests return 404
+
+**Validation**:
+
+- All tests pass
+- Coverage ≥ 85%
+
+### Step 7: Update Documentation [10 min]
+
+**Files**:
+
+- `docs/api/[resource].md` (API documentation)
+- OpenAPI/Swagger spec (if applicable)
+
+**Actions**:
+
+- Document all endpoints
+- Include request/response examples
+- Document error responses
+
+**Validation**:
+
+- Documentation is accurate
+- Examples work
+
+## TESTING STRATEGY
+
+### Unit Tests (Vitest)
+
+**Coverage Target**: 85%
+
+**Test Scenarios**:
+
+- Service layer methods with valid inputs
+- Service layer methods with invalid inputs
+- Repository methods (with test database)
+- Error handling paths
+
+### Integration Tests (Vitest + Testcontainers)
+
+**Coverage Target**: All endpoints
+
+**Test Scenarios**:
+
+- Happy path: Create, read, update, delete
+- Error cases: Invalid input, not found, unauthorized
+- Edge cases: Duplicate creation, concurrent updates
+- Authentication: Protected endpoints reject unauthenticated requests
+- Authorization: Protected endpoints enforce permissions
+
+### E2E Tests (Playwright)
+
+**Coverage Target**: Critical user flows (if user-facing)
+
+**Test Scenarios**:
+
+- [ADD_IF_USER_FACING: e.g., "User creates resource via UI"]
+
+## ROLLBACK STRATEGY
+
+### Immediate Rollback (< 5 minutes)
+
+1. Disable feature flag (if implemented)
+2. Restart service to previous version
+3. Monitor error logs and metrics
+
+### Database Rollback (if schema changes)
+
+1. Run down migration: `pnpm prisma migrate rollback`
+2. Verify data integrity
+3. Restart service
+
+### Validation
+
+- Service starts successfully
+- Existing functionality works
+- No data loss
+
+## EFFORT ESTIMATE
+
+**Total Estimated Time**: 2-3 hours
+
+**Breakdown**:
+
+- Types/schemas: 15 min
+- Repository: 20 min
+- Service layer: 20 min
+- Route handlers: 25 min
+- Error handling: 15 min
+- Tests: 30 min
+- Documentation: 10 min
+- Buffer (debugging, review): 30 min
+
+**Confidence Level**: High (standard pattern, well-understood)
+
+**Assumptions**:
+
+- No complex business logic
+- Standard CRUD operations
+- Existing database connection configured
+- Familiar with Express/TypeScript patterns
+
+---
+
+## CUSTOMIZATION CHECKLIST
+
+When using this template, replace the following placeholders:
+
+- [ ] [RESOURCE_NAME] - Name of the resource (e.g., "users", "posts", "orders")
+- [ ] [LIST_ENDPOINTS] - List of endpoints (e.g., "GET /users, POST /users")
+- [ ] [LIST_TABLES_REQUIRED] - Database tables needed
+- [ ] [LIST_SCHEMA_CHANGES] - Any schema modifications needed
+- [ ] [ADD_DATABASE_LIB] - Add if using specific ORM
+- [ ] [ADD_EXTERNAL_SERVICES] - Add if integrating external APIs
+- [ ] Adjust complexity scores based on actual requirements
+- [ ] Add/remove risks based on specific implementation
+- [ ] Customize test scenarios for specific business logic
+- [ ] Update time estimates based on team velocity
+
+---
+
+## PATTERN USAGE NOTES
+
+**When to Use This Template**:
+
+- ✅ Adding new CRUD endpoints
+- ✅ Standard RESTful API operations
+- ✅ Complexity score 2-5/10
+- ✅ No complex integrations
+
+**When NOT to Use**:
+
+- ❌ Complex multi-step workflows (use full planning)
+- ❌ GraphQL APIs (different pattern)
+- ❌ WebSocket/real-time features (different pattern)
+- ❌ Complexity > 6/10 (requires detailed analysis)
+
+**Time Savings**: 8-10 minutes vs full planning process

package/data/templates/plans/README.md

@@ -0,0 +1,174 @@
+# Plan Templates
+
+Plan templates accelerate the planning process for common implementation patterns by providing pre-structured plans with standard steps, dependencies, and risk mitigations.
+
+## Available Templates
+
+| Template                                              | Complexity Range | Time Savings | Use When                                                 |
+| ----------------------------------------------------- | ---------------- | ------------ | -------------------------------------------------------- |
+| [REST API](./PATTERN_REST_API.md)                     | 2-5/10           | 8-10 min     | Adding API endpoints, CRUD operations, RESTful resources |
+| [React Component](./PATTERN_REACT_COMPONENT.md)       | 2-5/10           | 8-10 min     | Building UI components, forms, pages                     |
+| [Database Migration](./PATTERN_DATABASE_MIGRATION.md) | 3-6/10           | 7-9 min      | Schema changes, data migrations, indexes                 |
+
+## Pattern Detection
+
+The planning system can auto-detect patterns based on task keywords:
+
+### REST API Pattern
+
+**Keywords**: `api`, `endpoint`, `rest`, `crud`, `http`, `route`, `handler`
+**File patterns**: `src/routes/`, `src/controllers/`, `*.routes.ts`
+
+**Example tasks**:
+
+- "Add users API endpoint"
+- "Create CRUD endpoints for posts"
+- "Implement GET /api/orders endpoint"
+
+### React Component Pattern
+
+**Keywords**: `component`, `react`, `ui`, `form`, `page`, `view`, `modal`
+**File patterns**: `src/components/`, `*.tsx`, `*.jsx`
+
+**Example tasks**:
+
+- "Add login form component"
+- "Create user profile page"
+- "Build notification modal"
+
+### Database Migration Pattern
+
+**Keywords**: `migration`, `schema`, `database`, `table`, `column`, `index`, `prisma`
+**File patterns**: `prisma/schema.prisma`, `migrations/`, `*.sql`
+
+**Example tasks**:
+
+- "Add email_verified column to users table"
+- "Create orders table with foreign keys"
+- "Add index to user email column"
+
+## Usage
+
+### Manual Template Selection
+
+```bash
+# Specify template explicitly
+valora plan "Add users API" --template=rest-api
+
+# Or use pattern name
+valora plan "Add users API" --pattern=rest-api
+```
+
+### Automatic Pattern Detection
+
+```bash
+# Planning system detects pattern automatically
+valora plan "Add login form component"
+# → Detects "React Component" pattern
+# → Uses PATTERN_REACT_COMPONENT.md template
+
+valora plan "Create users API endpoint"
+# → Detects "REST API" pattern
+# → Uses PATTERN_REST_API.md template
+```
+
+### Override Pattern Detection
+
+```bash
+# Force full planning even if pattern detected
+valora plan "Add users API" --no-template
+```
+
+## Template Structure
+
+Each template follows this structure:
+
+1. **Metadata** (YAML frontmatter)
+   - Pattern name
+   - Complexity range
+   - Use cases
+   - Applicable technologies
+
+2. **Overview**
+   - Task summary
+   - Scope definition
+   - Success criteria
+
+3. **Pre-filled Sections**
+   - Complexity assessment with typical scores
+   - Standard dependencies
+   - Common risks with mitigations
+   - Step-by-step implementation guide
+   - Testing strategy
+   - Rollback procedures
+
+4. **Customization Checklist**
+   - Placeholders to replace
+   - Adjustments needed
+
+## Benefits
+
+### Time Savings
+
+- **Without template**: 13-15 minutes for full planning
+- **With template**: 3-5 minutes for customization
+- **Savings**: 8-10 minutes per plan (~60% reduction)
+
+### Consistency
+
+- Standard structure across similar implementations
+- Best practices built into templates
+- Reduced planning errors
+
+### Quality
+
+- Pre-identified risks and mitigations
+- Comprehensive test strategies
+- Proven implementation steps
+
+## When NOT to Use Templates
+
+Templates are optimized for **low-to-moderate complexity** tasks. Use full planning for:
+
+- ❌ Complexity > 6/10
+- ❌ Novel or experimental implementations
+- ❌ Complex integrations (> 3 external services)
+- ❌ Major architectural changes
+- ❌ Multi-step workflows with state machines
+- ❌ High-risk changes (data loss potential, security critical)
+
+## Creating New Templates
+
+To add a new pattern template:
+
+1. Create `PATTERN_[NAME].md` in this directory
+2. Use existing templates as reference
+3. Include YAML frontmatter with metadata
+4. Add pattern detection keywords
+5. Update this README with new pattern
+6. Update `assess-complexity.md` prompt with detection logic
+
+### Template Naming Convention
+
+- File: `PATTERN_[UPPERCASE_NAME].md`
+- Pattern ID: `lowercase-name` (used in CLI)
+- Examples:
+  - `PATTERN_REST_API.md` → `rest-api`
+  - `PATTERN_REACT_COMPONENT.md` → `react-component`
+  - `PATTERN_DATABASE_MIGRATION.md` → `database-migration`
+
+## Metrics
+
+Track template effectiveness:
+
+- **Usage rate**: % of plans using templates
+- **Time savings**: Actual vs expected planning time
+- **Quality**: Template-based plans vs full plans (review scores)
+- **Feedback**: User satisfaction with templates
+
+Target metrics:
+
+- Usage rate: > 40% of plans
+- Time savings: 8-10 min per template use
+- Quality: Review scores ≥ 7.5/10
+- Satisfaction: > 80% find templates helpful