@relipa/ai-flow-kit 0.2.0 → 0.2.2-beta.0

package/README.md

@@ -80,8 +80,8 @@ ak execute PROJ-44  (or ./testcases.md  or  ak execute)
         │
         ▼
 ⛩️ GATE 1 — Pre-flight & Work Plan           [AI + QA]
-  Parse TC file → verify ak-test/{repo}/ exists
-  Check BASE_URL env var + playwright.config.ts
+  Parse TC file → verify AK-Docs/03.Testing/ subfolders exist
+  Check BASE_URL env var + playwright.config.ts + .gitignore covers 04.Evidence/
   Create execution work plan
   QA reviews → "APPROVED"
         │ APPROVED
@@ -341,9 +341,9 @@ ak execute
 ```
 
 **What happens (4-gate Execute Flow):**
-1. **Gate 1 — Pre-flight:** Parse TC file, verify `ak-test/{repo}/` exists, check `BASE_URL` and `playwright.config.ts` — QA reviews → `APPROVED`
+1. **Gate 1 — Pre-flight:** Parse TC file, verify `AK-Docs/03.Testing/` subfolders exist, check `BASE_URL`, `playwright.config.ts`, and `.gitignore` covers `04.Evidence/` — QA reviews → `APPROVED`
 2. **Gate 2 — Script Sync:** Hash-based TC↔script sync — gen new, update changed, skip unchanged (never fabricates selectors — uses Playwright MCP)
-3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence per `run-{N}/`, update TC file R1/R2 columns — QA reviews → `APPROVED`
+3. **Gate 3 — Execute & Evidence:** Run Playwright from `AK-Docs/03.Testing/05.Scripts/`, evidence lands in `04.Evidence/` (gitignored) per `run-{N}/`, update TC file R1/R2 columns — QA reviews → `APPROVED`
 4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, ask per-bug Jira confirmation — QA reviews → `APPROVED`
 
 > **Multi-AI:** Works with Claude, Codex, Gemini, Cursor, Copilot — the execute-flow skill is loaded via `ak init`/`ak up`.

package/custom/rules/java/spring-boot-rules.md

@@ -0,0 +1,209 @@
+# Spring Boot Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any Java code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## Architecture
+
+Follow strict **Layered Architecture**:
+
+```
+Controller (HTTP layer)
+    ↓
+Service (Business logic)
+    ↓
+Repository (Data access - Spring Data JPA)
+    ↓
+Entity / Domain Model
+```
+
+### Package Structure
+
+```
+com.company.project/
+├── controller/         # \@RestController — HTTP endpoints only
+├── service/
+│   ├── impl/           # \@Service — business logic implementation
+│   └── [Interface].java
+├── repository/         # \@Repository — extends JpaRepository
+├── entity/             # \@Entity — JPA entities
+├── dto/
+│   ├── request/        # Input DTOs (e.g. CreateUserRequest)
+│   └── response/       # Output DTOs (e.g. UserResponse)
+├── mapper/             # MapStruct mappers (Entity ↔ DTO)
+├── exception/
+│   ├── GlobalExceptionHandler.java  # \@RestControllerAdvice
+│   └── [CustomException].java
+├── config/             # \@Configuration classes
+└── util/               # Pure utility helpers (stateless)
+```
+
+---
+
+## Controller Rules
+
+- Annotate with `\@RestController` + `\@RequestMapping`
+- **Only** handle HTTP concerns: parse request, call service, return response
+- Never put business logic in Controller
+- Always use DTOs — never expose Entity directly
+- Use `ResponseEntity<T>` for explicit HTTP status control
+- Validate input with `\@Valid` + Bean Validation annotations
+
+---
+
+## Service Rules
+
+- Always define an **interface**, implement in the `impl/` package
+- Annotate implementation with `\@Service`
+- All business logic lives here
+- Use `\@Transactional` at the method level (not class level)
+- Throw specific custom exceptions, not generic `RuntimeException`
+- Never return an Entity — always convert to DTO via Mapper
+
+---
+
+## Repository Rules
+
+- Extend `JpaRepository<Entity, ID>`
+- Use **method name queries** for simple queries
+- Use `\@Query` (JPQL) for complex queries — avoid native SQL unless necessary
+- Never add business logic here
+- Use `\@EntityGraph` to solve N+1 problems
+
+---
+
+## Entity Rules
+
+- Use Lombok: `\@Getter`, `\@Setter`, `\@NoArgsConstructor`, `\@AllArgsConstructor`, `\@Builder`
+- Avoid `\@Data` on entities (causes issues with `equals/hashCode` + lazy loading)
+- Always use `\@Table(name = "snake_case_table_name")`
+- Use `\@Column(name = "snake_case_column_name")` explicitly
+- For soft delete: add `deleted` boolean + `deletedAt` timestamp
+- Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
+
+---
+
+## DTO Rules
+
+- Use separate DTOs for **Request** and **Response** — never share
+- Use Lombok: `\@Getter`, `\@Builder`, `\@AllArgsConstructor`, `\@NoArgsConstructor`
+- Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
+- Never expose internal fields (password hash, audit timestamps) in the Response DTO
+
+---
+
+## MapStruct Mapper Rules
+
+- Use `\@Mapper(componentModel = "spring")` — inject as a Spring bean
+- Define explicit mappings with `\@Mapping` when field names differ
+- Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
+
+---
+
+## Exception Handling
+
+- Create custom exceptions extending `RuntimeException`
+- Handle all exceptions in one `\@RestControllerAdvice` class
+- Return a consistent error response format
+- Never expose stack traces to the client
+
+---
+
+## Testing Rules
+
+### Unit Tests (Service layer)
+- Test class: `[ServiceImpl]Test.java`
+- Mock all dependencies with `\@ExtendWith(MockitoExtension.class)` + `\@Mock`
+- Test happy path + edge cases + exception scenarios
+- Use AssertJ: `assertThat(result).isEqualTo(expected)`
+
+### Integration Tests (Controller layer)
+- Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
+- Test full HTTP flow with `MockMvc`
+- Use `\@Sql` or Testcontainers for database state
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Class | PascalCase | `UserService`, `OrderController` |
+| Method | camelCase | `findById`, `createOrder` |
+| Variable | camelCase | `userResponse`, `orderId` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Package | lowercase | `com.company.project.service` |
+| DB Table | snake_case | `user_orders`, `product_items` |
+| DB Column | snake_case | `created_at`, `user_id` |
+| REST endpoint | kebab-case | `/api/v1/user-profiles` |
+| Request DTO | `[Action][Resource]Request` | `CreateOrderRequest` |
+| Response DTO | `[Resource]Response` | `OrderResponse` |
+
+---
+
+## API Design
+
+- Version all APIs: `/api/v1/...`
+- Use plural nouns for resources: `/users`, `/orders`
+- HTTP methods: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial), `DELETE`
+- Return `201 Created` for POST, `200 OK` for GET/PUT/PATCH, `204 No Content` for DELETE
+- Use consistent pagination: `?page=0&size=20&sort=createdAt,desc`
+
+```
+GET    /api/v1/users              → 200 list
+POST   /api/v1/users              → 201 created
+GET    /api/v1/users/{id}         → 200 or 404
+PUT    /api/v1/users/{id}         → 200 or 404
+DELETE /api/v1/users/{id}         → 204 or 404
+GET    /api/v1/users/{id}/orders  → 200 nested resource
+```
+
+---
+
+## Performance Rules
+
+- Always use pagination — never return unbounded lists
+- Avoid N+1: use `\@EntityGraph` or `JOIN FETCH` in JPQL
+- Add database indexes on frequently queried columns
+- Use `\@Transactional(readOnly = true)` on read-only service methods
+- For heavy read operations, consider projection interfaces
+
+---
+
+## Security Rules
+
+- Never log passwords, tokens, or sensitive PII
+- Hash passwords with BCrypt: `passwordEncoder.encode(rawPassword)`
+- Validate and sanitize all user inputs via Bean Validation
+- Use `\@PreAuthorize` for method-level security
+- Never return stack traces to API consumers
+- Store secrets in environment variables / Vault — never in code
+
+---
+
+## Logging Rules
+
+- Use SLF4J with Lombok `\@Slf4j`
+- `log.info` — normal business events
+- `log.warn` — recoverable issues (not found, validation fail)
+- `log.error` — unexpected exceptions (always include `ex` as the second argument)
+- Never log sensitive data (password, credit card, token)
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ `\@Autowired` field injection → use constructor injection (Lombok `\@RequiredArgsConstructor`)
+- ❌ `\@Data` on JPA entities → use `\@Getter \@Setter` separately
+- ❌ Returning `Entity` directly from Controller → always use DTO
+- ❌ `SELECT *` or unbounded `findAll()` → always paginate
+- ❌ Business logic in Controller → move to Service
+- ❌ Catching and swallowing exceptions → handle properly or rethrow
+- ❌ `new RuntimeException("something")` → create a specific custom exception
+- ❌ Hardcoding config values → use `\@Value` or `\@ConfigurationProperties`
+- ❌ `\@Transactional` on Controller → only on Service methods
+
+---
+
+When explaining changes, refer to the [Spring Boot Official Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) and [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/) conventions.

package/custom/rules/javascript/nestjs-examples.md

@@ -0,0 +1,41 @@
+# NestJS Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## NestJS Rules
+
+```typescript
+// ✅ Good: DTO with validation
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  password: string;
+}
+```
+
+---
+
+## Testing
+
+```typescript
+describe('UsersService', () => {
+  let service: UsersService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [UsersService],
+    }).compile();
+
+    service = module.get<UsersService>(UsersService);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+});
+```

package/custom/rules/javascript/nestjs-rules.md

@@ -0,0 +1,42 @@
+# NestJS Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any NestJS code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## Project Architecture
+
+NestJS follows a strict **Module-based** architecture. Every feature should be contained in its own module.
+
+```
+src/
+├── app.module.ts
+├── main.ts
+└── features/
+    └── [feature-name]/
+        ├── [feature].module.ts
+        ├── [feature].controller.ts
+        ├── [feature].service.ts
+        ├── [feature].entity.ts (if using TypeORM)
+        └── dto/
+            ├── create-[feature].dto.ts
+            └── update-[feature].dto.ts
+```
+
+---
+
+## NestJS Rules
+
+- Use **Constructor Injection** for all dependencies.
+- Always use **DTOs** (Data Transfer Objects) with `class-validator` for input validation.
+- Annotate controllers with `@Controller()`.
+- Use `@Injectable()` for services.
+- Leverage **Pipes** for data transformation and validation.
+- Leverage **Interceptors** for logging and response mapping.
+
+---
+
+## Testing Rules
+
+- Use the built-in **Jest** testing suite.
+- Use `Test.createTestingModule` to create isolated environments for unit tests.

package/custom/rules/javascript/nodejs-express-examples.md

@@ -0,0 +1,35 @@
+# Node.js Express Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## Express Rules
+
+```javascript
+// ✅ Good: Controller calls service
+export const createUser = async (req, res, next) => {
+    const userData = req.body;
+    const user = await userService.create(userData);
+    res.status(201).json(user);
+};
+```
+
+---
+
+## Testing
+
+```javascript
+// Example test
+import request from 'supertest';
+import app from '../app';
+
+describe('POST /api/users', () => {
+    it('should create a new user', async () => {
+        const response = await request(app)
+            .post('/api/users')
+            .send({ email: 'test@example.com', password: 'password123' });
+        expect(response.status).toBe(201);
+    });
+});
+```

package/custom/rules/javascript/nodejs-express-rules.md

@@ -0,0 +1,49 @@
+# Node.js Express Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any Express code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## Project Structure
+
+Follow the **Controller-Service-Repository** pattern:
+
+```
+src/
+├── controllers/    # Route handlers — parse input, call service, return response
+├── services/       # Business logic — core logic, database transactions
+├── repositories/   # Data access — database queries, ORM interactions
+├── models/         # Database models (Sequelize/Prisma/Mongoose)
+├── middleware/     # Custom Express middleware (auth, logging)
+├── routes/         # Route definitions
+├── dtos/           # Input/Output Data Transfer Objects (if using TS)
+├── utils/          # Stateless helper functions
+└── config/         # App configuration
+```
+
+---
+
+## Express Rules
+
+- Use **Async/Await** for all asynchronous operations — avoid callbacks or manual promise chains.
+- Always use a global error handler middleware. Never use `try/catch` in controllers if you use an async-wrapper middleware.
+- Validate all incoming data using `Joi`, `Zod`, or `express-validator`.
+- Keep controllers thin; they should only handle request parsing and response formatting.
+
+---
+
+## Security Rules
+
+- Never expose stack traces in production.
+- Use `helmet` to set secure HTTP headers.
+- Sanitize input to prevent NoSQL/SQL injection.
+- Use `argon2` or `bcrypt` for password hashing.
+- Standardize on JWT for authentication.
+
+---
+
+## Testing Rules
+
+- Use **Jest** and **Supertest** for testing.
+- Test every API endpoint with integration tests.
+- Mock external services (Email, Payment Gateways).