kiro-spec-engine 1.3.0 → 1.4.0

package/docs/examples/add-rest-api/requirements.md

@@ -0,0 +1,323 @@
+# RESTful API with Authentication - Requirements
+
+> Example Spec demonstrating API feature development
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Spec Type**: Example - API Feature
+
+---
+
+## Overview
+
+This Spec demonstrates how to structure requirements for a RESTful API feature. We'll build a simple task management API with JWT authentication, covering common API patterns like CRUD operations, authentication, authorization, and error handling.
+
+**Learning Points:**
+- API endpoint design
+- Authentication and authorization
+- Request/response formats
+- Error handling
+- API versioning
+
+---
+
+## User Stories
+
+### US-1: User Registration
+**As a** new user  
+**I want to** register an account with email and password  
+**So that** I can access the task management system
+
+**Acceptance Criteria:**
+- WHEN I POST to `/api/v1/auth/register` with valid email and password THEN I receive a success response with user ID
+- WHEN I register with an existing email THEN I receive a 409 Conflict error
+- WHEN I register with invalid email format THEN I receive a 400 Bad Request error
+- WHEN I register with password < 8 characters THEN I receive a 400 Bad Request error
+
+---
+
+### US-2: User Login
+**As a** registered user  
+**I want to** log in with my credentials  
+**So that** I can access my tasks
+
+**Acceptance Criteria:**
+- WHEN I POST to `/api/v1/auth/login` with valid credentials THEN I receive a JWT token
+- WHEN I login with invalid credentials THEN I receive a 401 Unauthorized error
+- WHEN I login successfully THEN the token expires after 24 hours
+- WHEN I use an expired token THEN I receive a 401 Unauthorized error
+
+---
+
+### US-3: Create Task
+**As an** authenticated user  
+**I want to** create a new task  
+**So that** I can track my work
+
+**Acceptance Criteria:**
+- WHEN I POST to `/api/v1/tasks` with valid token and task data THEN I receive the created task with ID
+- WHEN I create a task without authentication THEN I receive a 401 Unauthorized error
+- WHEN I create a task with missing required fields THEN I receive a 400 Bad Request error
+- WHEN I create a task successfully THEN it's associated with my user ID
+
+---
+
+### US-4: List Tasks
+**As an** authenticated user  
+**I want to** view all my tasks  
+**So that** I can see what I need to do
+
+**Acceptance Criteria:**
+- WHEN I GET `/api/v1/tasks` with valid token THEN I receive a list of my tasks
+- WHEN I list tasks without authentication THEN I receive a 401 Unauthorized error
+- WHEN I have no tasks THEN I receive an empty array
+- WHEN I have multiple tasks THEN they are sorted by creation date (newest first)
+
+---
+
+### US-5: Update Task
+**As an** authenticated user  
+**I want to** update a task's details  
+**So that** I can modify task information
+
+**Acceptance Criteria:**
+- WHEN I PUT `/api/v1/tasks/:id` with valid token and data THEN the task is updated
+- WHEN I update another user's task THEN I receive a 403 Forbidden error
+- WHEN I update a non-existent task THEN I receive a 404 Not Found error
+- WHEN I update with invalid data THEN I receive a 400 Bad Request error
+
+---
+
+### US-6: Delete Task
+**As an** authenticated user  
+**I want to** delete a task  
+**So that** I can remove completed or unwanted tasks
+
+**Acceptance Criteria:**
+- WHEN I DELETE `/api/v1/tasks/:id` with valid token THEN the task is deleted
+- WHEN I delete another user's task THEN I receive a 403 Forbidden error
+- WHEN I delete a non-existent task THEN I receive a 404 Not Found error
+- WHEN I delete successfully THEN I receive a 204 No Content response
+
+---
+
+## Functional Requirements
+
+### FR-1: Authentication System
+The system must provide JWT-based authentication for API access.
+
+**Details:**
+- Support user registration with email and password
+- Support user login with credentials
+- Generate JWT tokens with 24-hour expiration
+- Validate JWT tokens on protected endpoints
+- Hash passwords using bcrypt (10 rounds)
+
+---
+
+### FR-2: Task CRUD Operations
+The system must provide complete CRUD operations for tasks.
+
+**Details:**
+- Create: POST `/api/v1/tasks`
+- Read (list): GET `/api/v1/tasks`
+- Read (single): GET `/api/v1/tasks/:id`
+- Update: PUT `/api/v1/tasks/:id`
+- Delete: DELETE `/api/v1/tasks/:id`
+
+---
+
+### FR-3: Authorization
+The system must enforce user-level authorization for task operations.
+
+**Details:**
+- Users can only access their own tasks
+- Users cannot view, update, or delete other users' tasks
+- Return 403 Forbidden for unauthorized access attempts
+
+---
+
+### FR-4: Input Validation
+The system must validate all input data before processing.
+
+**Details:**
+- Email: Valid email format, max 255 characters
+- Password: Minimum 8 characters, max 128 characters
+- Task title: Required, max 200 characters
+- Task description: Optional, max 2000 characters
+- Task status: Enum (pending, in_progress, completed)
+
+---
+
+### FR-5: Error Handling
+The system must provide consistent error responses.
+
+**Details:**
+- Use standard HTTP status codes
+- Return JSON error responses with message and error code
+- Include validation errors with field-specific messages
+- Log errors for debugging
+
+---
+
+### FR-6: API Versioning
+The system must support API versioning for future compatibility.
+
+**Details:**
+- All endpoints prefixed with `/api/v1/`
+- Version included in URL path
+- Support for future versions without breaking existing clients
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Performance
+- API response time < 200ms for 95% of requests
+- Support 100 concurrent users
+- Database queries optimized with indexes
+
+### NFR-2: Security
+- Passwords hashed with bcrypt
+- JWT tokens signed with secret key
+- HTTPS required in production
+- Rate limiting: 100 requests per minute per IP
+- Input sanitization to prevent injection attacks
+
+### NFR-3: Reliability
+- 99.9% uptime
+- Graceful error handling (no crashes)
+- Database transactions for data consistency
+
+### NFR-4: Maintainability
+- RESTful API design principles
+- Consistent naming conventions
+- Comprehensive API documentation
+- Unit test coverage > 80%
+
+### NFR-5: Scalability
+- Stateless API design (horizontal scaling)
+- Database connection pooling
+- Caching for frequently accessed data
+
+---
+
+## API Endpoints Summary
+
+| Method | Endpoint | Auth Required | Description |
+|--------|----------|---------------|-------------|
+| POST | `/api/v1/auth/register` | No | Register new user |
+| POST | `/api/v1/auth/login` | No | Login user |
+| POST | `/api/v1/tasks` | Yes | Create task |
+| GET | `/api/v1/tasks` | Yes | List all user's tasks |
+| GET | `/api/v1/tasks/:id` | Yes | Get single task |
+| PUT | `/api/v1/tasks/:id` | Yes | Update task |
+| DELETE | `/api/v1/tasks/:id` | Yes | Delete task |
+
+---
+
+## Data Models
+
+### User
+```json
+{
+  "id": "uuid",
+  "email": "string (unique)",
+  "password": "string (hashed)",
+  "createdAt": "timestamp",
+  "updatedAt": "timestamp"
+}
+```
+
+### Task
+```json
+{
+  "id": "uuid",
+  "userId": "uuid (foreign key)",
+  "title": "string",
+  "description": "string (optional)",
+  "status": "enum (pending, in_progress, completed)",
+  "createdAt": "timestamp",
+  "updatedAt": "timestamp"
+}
+```
+
+---
+
+## Error Response Format
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error message",
+    "details": {
+      "field": "Specific field error (for validation)"
+    }
+  }
+}
+```
+
+**Error Codes:**
+- `INVALID_INPUT` - Validation error
+- `UNAUTHORIZED` - Authentication required
+- `FORBIDDEN` - Insufficient permissions
+- `NOT_FOUND` - Resource not found
+- `CONFLICT` - Resource already exists
+- `INTERNAL_ERROR` - Server error
+
+---
+
+## Out of Scope
+
+The following are explicitly out of scope for this Spec:
+
+- ❌ Password reset functionality
+- ❌ Email verification
+- ❌ OAuth/social login
+- ❌ Task sharing between users
+- ❌ Task categories or tags
+- ❌ File attachments
+- ❌ Real-time notifications
+- ❌ Admin panel
+
+---
+
+## Dependencies
+
+- **Node.js** 14+ - Runtime environment
+- **Express.js** 4.x - Web framework
+- **PostgreSQL** 13+ - Database
+- **jsonwebtoken** - JWT implementation
+- **bcrypt** - Password hashing
+- **express-validator** - Input validation
+
+---
+
+## Success Criteria
+
+This feature is considered complete when:
+
+1. ✅ All 7 API endpoints are implemented and working
+2. ✅ All acceptance criteria pass
+3. ✅ Unit test coverage > 80%
+4. ✅ Integration tests cover all endpoints
+5. ✅ API documentation is complete
+6. ✅ Security requirements are met
+7. ✅ Performance requirements are met
+
+---
+
+## Related Documentation
+
+- [Design Document](design.md) - Technical design and architecture
+- [Tasks Document](tasks.md) - Implementation plan
+- [API Documentation Guide](../../spec-workflow.md) - How to document APIs
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Status**: Example Spec

package/docs/examples/add-rest-api/tasks.md

@@ -0,0 +1,355 @@
+# RESTful API with Authentication - Tasks
+
+> Implementation plan for the task management API
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Spec Type**: Example - API Feature
+
+---
+
+## Overview
+
+This tasks document breaks down the implementation into logical phases. Each task is specific enough for an AI assistant to implement while maintaining flexibility for different approaches.
+
+**Estimated Total Time:** 12-16 hours  
+**Complexity:** Medium  
+**Prerequisites:** Node.js 14+, PostgreSQL 13+
+
+---
+
+## Phase 1: Project Setup
+
+**Estimated Time:** 1-2 hours
+
+- [ ] 1.1 Initialize Node.js project
+  - Create package.json with npm init
+  - Set up project structure (src/, tests/, config/)
+  - Create .gitignore file
+  - Create .env.example file
+
+- [ ] 1.2 Install dependencies
+  - Install express, pg, jsonwebtoken, bcrypt, express-validator, dotenv, uuid
+  - Install dev dependencies: jest, supertest, nodemon
+  - Configure package.json scripts (start, dev, test)
+
+- [ ] 1.3 Set up database
+  - Create PostgreSQL database
+  - Create users table with schema from design.md
+  - Create tasks table with schema from design.md
+  - Create indexes for performance
+
+- [ ] 1.4 Configure environment
+  - Create .env file with database credentials
+  - Create config/database.js for database connection
+  - Create config/jwt.js for JWT configuration
+  - Test database connection
+
+---
+
+## Phase 2: Core Infrastructure
+
+**Estimated Time:** 2-3 hours
+
+- [ ] 2.1 Create error handling system
+  - Implement custom error classes (AppError, ValidationError, etc.)
+  - Create error handler middleware
+  - Add error logging utility
+  - Test error handling
+
+- [ ] 2.2 Create Express app structure
+  - Create src/app.js with Express setup
+  - Configure middleware (json parser, cors, etc.)
+  - Set up route mounting
+  - Add error handler middleware
+
+- [ ] 2.3 Create database connection pool
+  - Implement connection pool in config/database.js
+  - Add connection health check
+  - Handle connection errors gracefully
+  - Test connection pool
+
+- [ ] 2.4 Create validation utilities
+  - Set up express-validator
+  - Create reusable validation middleware
+  - Test validation error formatting
+
+---
+
+## Phase 3: Authentication System
+
+**Estimated Time:** 3-4 hours
+
+- [ ] 3.1 Implement UserRepository
+  - Create src/repositories/user.repository.js
+  - Implement create() method
+  - Implement findByEmail() method
+  - Implement findById() method
+  - Write unit tests for repository
+
+- [ ] 3.2 Implement AuthService
+  - Create src/services/auth.service.js
+  - Implement register() method with password hashing
+  - Implement login() method with password verification
+  - Implement generateToken() method
+  - Write unit tests for service
+
+- [ ] 3.3 Implement AuthController
+  - Create src/controllers/auth.controller.js
+  - Implement register() endpoint handler
+  - Implement login() endpoint handler
+  - Handle validation errors
+  - Write unit tests for controller
+
+- [ ] 3.4 Create authentication middleware
+  - Create src/middleware/auth.middleware.js
+  - Implement JWT token verification
+  - Extract user from token and attach to request
+  - Handle authentication errors
+  - Write unit tests for middleware
+
+- [ ] 3.5 Create auth validators
+  - Create src/validators/auth.validator.js
+  - Implement registration validation rules
+  - Implement login validation rules
+  - Test validation rules
+
+- [ ] 3.6 Create auth routes
+  - Create src/routes/auth.routes.js
+  - Define POST /api/v1/auth/register route
+  - Define POST /api/v1/auth/login route
+  - Mount routes in app.js
+  - Write integration tests for auth endpoints
+
+---
+
+## Phase 4: Task Management System
+
+**Estimated Time:** 3-4 hours
+
+- [ ] 4.1 Implement TaskRepository
+  - Create src/repositories/task.repository.js
+  - Implement create() method
+  - Implement findByUserId() method
+  - Implement findById() method
+  - Implement update() method
+  - Implement delete() method
+  - Write unit tests for repository
+
+- [ ] 4.2 Implement TaskService
+  - Create src/services/task.service.js
+  - Implement create() method
+  - Implement findByUserId() method with sorting
+  - Implement findById() method
+  - Implement update() method
+  - Implement delete() method
+  - Write unit tests for service
+
+- [ ] 4.3 Implement TaskController
+  - Create src/controllers/task.controller.js
+  - Implement create() endpoint handler
+  - Implement list() endpoint handler
+  - Implement getById() endpoint handler with ownership check
+  - Implement update() endpoint handler with ownership check
+  - Implement delete() endpoint handler with ownership check
+  - Write unit tests for controller
+
+- [ ] 4.4 Create task validators
+  - Create src/validators/task.validator.js
+  - Implement task creation validation rules
+  - Implement task update validation rules
+  - Test validation rules
+
+- [ ] 4.5 Create task routes
+  - Create src/routes/task.routes.js
+  - Apply authentication middleware to all routes
+  - Define POST /api/v1/tasks route
+  - Define GET /api/v1/tasks route
+  - Define GET /api/v1/tasks/:id route
+  - Define PUT /api/v1/tasks/:id route
+  - Define DELETE /api/v1/tasks/:id route
+  - Mount routes in app.js
+  - Write integration tests for task endpoints
+
+---
+
+## Phase 5: Security & Performance
+
+**Estimated Time:** 2-3 hours
+
+- [ ] 5.1 Implement rate limiting
+  - Create src/middleware/rate-limit.middleware.js
+  - Configure rate limiting (100 requests per minute)
+  - Apply to all routes
+  - Test rate limiting
+
+- [ ] 5.2 Add input sanitization
+  - Add sanitization to validators
+  - Prevent SQL injection
+  - Prevent XSS attacks
+  - Test sanitization
+
+- [ ] 5.3 Optimize database queries
+  - Add database indexes (already in schema)
+  - Implement connection pooling (already done)
+  - Add query logging for debugging
+  - Test query performance
+
+- [ ] 5.4 Add security headers
+  - Install helmet middleware
+  - Configure security headers
+  - Test security headers
+
+---
+
+## Phase 6: Testing & Documentation
+
+**Estimated Time:** 2-3 hours
+
+- [ ] 6.1 Write comprehensive unit tests
+  - Test all repository methods
+  - Test all service methods
+  - Test all controller methods
+  - Test all middleware
+  - Achieve > 80% code coverage
+
+- [ ] 6.2 Write integration tests
+  - Test complete registration flow
+  - Test complete login flow
+  - Test complete task CRUD flow
+  - Test authentication failures
+  - Test authorization failures
+  - Test validation errors
+
+- [ ] 6.3 Create API documentation
+  - Document all endpoints with examples
+  - Document request/response formats
+  - Document error responses
+  - Document authentication flow
+  - Create Postman collection or OpenAPI spec
+
+- [ ] 6.4 Add code comments
+  - Add JSDoc comments to all functions
+  - Document complex logic
+  - Add usage examples in comments
+
+---
+
+## Phase 7: Deployment Preparation
+
+**Estimated Time:** 1-2 hours
+
+- [ ] 7.1 Create production configuration
+  - Create production .env template
+  - Configure production database settings
+  - Set up HTTPS requirements
+  - Configure logging for production
+
+- [ ] 7.2 Add health check endpoint
+  - Create GET /api/v1/health endpoint
+  - Check database connection
+  - Return system status
+  - Test health check
+
+- [ ] 7.3 Create deployment scripts
+  - Create database migration scripts
+  - Create seed data scripts (optional)
+  - Create deployment documentation
+  - Test deployment process
+
+- [ ] 7.4 Final testing
+  - Run all unit tests
+  - Run all integration tests
+  - Test with production-like data
+  - Verify all acceptance criteria
+
+---
+
+## Verification Checklist
+
+Before marking this Spec as complete, verify:
+
+### Functionality
+- [ ] All 7 API endpoints work correctly
+- [ ] Authentication works (register, login, token verification)
+- [ ] Authorization works (users can only access their own tasks)
+- [ ] Input validation works for all endpoints
+- [ ] Error handling works for all error cases
+
+### Testing
+- [ ] Unit test coverage > 80%
+- [ ] All integration tests pass
+- [ ] All acceptance criteria from requirements.md pass
+- [ ] Manual testing completed
+
+### Security
+- [ ] Passwords are hashed with bcrypt
+- [ ] JWT tokens are properly signed and verified
+- [ ] Rate limiting is active
+- [ ] Input sanitization prevents injection attacks
+- [ ] Security headers are configured
+
+### Performance
+- [ ] API response time < 200ms for 95% of requests
+- [ ] Database queries are optimized with indexes
+- [ ] Connection pooling is configured
+
+### Documentation
+- [ ] API documentation is complete
+- [ ] Code has JSDoc comments
+- [ ] README has setup instructions
+- [ ] Environment variables are documented
+
+---
+
+## Notes for AI Implementation
+
+**When implementing this Spec:**
+
+1. **Follow the phase order** - Each phase builds on the previous one
+2. **Test as you go** - Write tests for each component before moving on
+3. **Use the design document** - Refer to design.md for exact method signatures and logic
+4. **Handle errors properly** - Use the custom error classes from design.md
+5. **Validate all inputs** - Use express-validator as specified
+6. **Check ownership** - Always verify users can only access their own tasks
+7. **Keep it simple** - Don't add features not in requirements.md
+
+**Common pitfalls to avoid:**
+
+- ❌ Don't skip error handling
+- ❌ Don't forget to hash passwords
+- ❌ Don't skip input validation
+- ❌ Don't forget ownership checks on task operations
+- ❌ Don't hardcode configuration values
+- ❌ Don't skip tests
+
+**Example AI prompt:**
+
+```
+I'm implementing a RESTful API with authentication. Please implement Phase 3, Task 3.2: AuthService.
+
+Requirements:
+- See requirements.md for user stories and acceptance criteria
+- See design.md for exact method signatures and logic
+- Use bcrypt for password hashing (10 rounds)
+- Use jsonwebtoken for token generation (24-hour expiration)
+- Throw appropriate custom errors (UnauthorizedError, ConflictError)
+
+Please implement the complete AuthService class with all methods and error handling.
+```
+
+---
+
+## Related Documentation
+
+- [Requirements Document](requirements.md) - Feature requirements and acceptance criteria
+- [Design Document](design.md) - Technical design and architecture
+- [Spec Workflow Guide](../../spec-workflow.md) - Understanding Specs
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Status**: Example Spec