ginskill-init 1.0.0

package/skills/review-code/references/nestjs-patterns.md

@@ -0,0 +1,184 @@
+# NestJS Patterns — Backend Review Reference
+
+Quick reference for reviewing NestJS backend code.
+
+## Table of Contents
+1. [Module Structure](#module-structure)
+2. [Controller Conventions](#controller-conventions)
+3. [Service Patterns](#service-patterns)
+4. [Schema / Entity Patterns](#schema--entity-patterns)
+5. [DTO Validation](#dto-validation)
+6. [Error Handling](#error-handling)
+7. [Auth & Guards](#auth--guards)
+8. [AI Agent Patterns](#ai-agent-patterns)
+
+---
+
+## Module Structure
+
+Every feature module follows this layout:
+```
+features/<name>/
+├── <name>.module.ts         # @Module declaration
+├── <name>.controller.ts     # HTTP routes
+├── <name>.service.ts        # Business logic
+├── dto/                     # class-validator DTOs
+├── entities/                # Mongoose schemas
+├── interfaces/              # TypeScript interfaces
+└── __tests__/               # Jest tests (when they exist)
+```
+
+Module registration in `app.module.ts` — all feature modules are imported at the root level.
+
+## Controller Conventions
+
+```typescript
+@Controller('items')
+@ApiTags('Items')
+@UseGuards(JwtAuthGuard)            // Protect all routes
+export class ItemController {
+  constructor(private readonly itemService: ItemService) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Create item' })
+  create(@Body() dto: CreateItemDto, @CurrentUser() user: User) {
+    return this.itemService.create(dto, user);
+  }
+}
+```
+
+Review checklist:
+- Controllers should be thin — validate input, delegate to service, return response (SRP)
+- No business logic, DB calls, or side effects in controllers (separation of concerns)
+- Use `@ApiTags` and `@ApiOperation` for Swagger docs
+- Use `@UseGuards(JwtAuthGuard)` for protected routes
+- Use `@CurrentUser()` decorator (from shared) to get authenticated user
+- Use proper HTTP methods and status codes
+- Controller methods should be <15 lines — if longer, logic belongs in the service
+- Avoid catch blocks in controllers — let exception filters handle errors
+
+## Service Patterns
+
+```typescript
+@Injectable()
+export class ItemService {
+  constructor(
+    @InjectModel(Item.name) private itemModel: Model<ItemDocument>,
+    private readonly mediaService: MediaService,
+  ) {}
+
+  async create(dto: CreateItemDto, user: User): Promise<Item> {
+    // Business logic here
+  }
+}
+```
+
+Review checklist:
+- Services own business logic, not controllers (SRP)
+- Inject dependencies through constructor (DIP) — never use `new` for services or `moduleRef.get()`
+- Use proper Mongoose model injection
+- Return typed responses — avoid `any`, use explicit return types on public methods
+- Handle errors with NestJS exceptions (`NotFoundException`, `BadRequestException`, etc.)
+- Keep services focused: <200 lines, <10 public methods. Split if growing beyond this (SRP)
+- Use early returns / guard clauses instead of deep nesting
+- Extract repeated query patterns to private helper methods (DRY)
+- Prefer composition over inheritance — inject other services rather than extending base classes
+- Avoid side effects in methods that read data (query methods shouldn't mutate state)
+
+## Schema / Entity Patterns
+
+```typescript
+@Schema({ timestamps: true, collection: 'items' })
+export class Item {
+  @Prop({ required: true })
+  name: string;
+
+  @Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true, index: true })
+  userId: mongoose.Types.ObjectId;
+
+  @Prop({ type: [String], default: [] })
+  tags: string[];
+}
+```
+
+Review checklist:
+- Use `{ timestamps: true }` for automatic createdAt/updatedAt
+- Add `required: true` on non-optional fields
+- Add `index: true` on fields used in queries
+- Use `ref` for cross-document references
+- Specify `collection` name explicitly
+
+## DTO Validation
+
+```typescript
+export class CreateItemDto {
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  tags?: string[];
+}
+```
+
+Review checklist:
+- All input DTOs should use class-validator decorators
+- Mark optional fields with `@IsOptional()`
+- Use `@Transform()` for sanitization when needed
+- Separate Create, Update, and Query DTOs
+
+## Error Handling
+
+The project should use a global `HttpExceptionFilter` in `core/exception/`.
+
+In services, throw typed NestJS exceptions:
+```typescript
+throw new NotFoundException('Item not found');
+throw new BadRequestException('Invalid input');
+throw new UnauthorizedException('Not authorized');
+throw new ConflictException('Item already exists');
+```
+
+Review checklist:
+- Never swallow errors silently (empty catch blocks) — this is a CRITICAL code smell
+- Use typed exceptions, not generic `Error` — exception type communicates intent
+- Log errors before throwing when there's useful context
+- Handle async errors — all async functions should have try/catch or let exceptions propagate meaningfully
+- **Fail fast**: Validate inputs at the boundary (controller/DTO), don't check deep in business logic
+- **Consistent strategy per layer**: Controllers use HTTP exceptions, services use domain exceptions, repositories propagate DB errors
+- Avoid `try/catch` around every line — wrap logical units, not individual statements
+- Include actionable context in error messages: `Item ${id} not found` not just `Not found`
+
+## Auth & Guards
+
+- `JwtAuthGuard` — Standard JWT Bearer token guard
+- `@CurrentUser()` — Extracts user from JWT payload
+- Role-based guards for admin/privileged operations
+
+Review checklist:
+- All non-public endpoints should have `@UseGuards(JwtAuthGuard)`
+- User-specific queries should filter by `userId` from `@CurrentUser()`
+- No endpoints should expose other users' data without admin check
+
+## AI Agent Patterns
+
+AI agent modules have their own internal architecture:
+
+```
+ai-agents/core/
+├── llm/services/              # Abstraction layer for all LLM calls
+├── providers/                 # Provider configs (OpenAI, Gemini, Vertex AI)
+├── graph/                     # LangGraph state machine
+├── tools/                     # Custom tools the agent can call
+├── knowledge/                 # Knowledge base (embeddings → vector DB)
+└── config/                    # System prompts, tool configs
+```
+
+Review checklist:
+- LLM calls should go through the abstraction layer, not direct SDK calls
+- New tools should follow the existing pattern (DynamicStructuredTool)
+- System prompts should use reusable sections from config
+- Token limits and timeouts should be configured, not hardcoded
+- Retry logic should use circuit breakers

package/skills/review-code/scripts/check-module.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────
+# Module Health Check
+#
+# Quickly audit a single NestJS feature module for completeness:
+#   - Has module.ts, controller.ts, service.ts?
+#   - Has DTOs with validation decorators?
+#   - Has Mongoose schemas with proper decorators?
+#   - Has tests?
+#   - Has Swagger decorators?
+#   - Uses auth guards?
+#
+# Auto-detects backend directory from repo root.
+#
+# Usage:
+#   ./check-module.sh item
+#   ./check-module.sh auth
+#
+# Environment variables (override auto-detection):
+#   BE_SRC=./my-backend/src  ./check-module.sh item
+# ─────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || cd "$SCRIPT_DIR/../../../../.." && pwd)"
+
+# ─── Auto-detect backend src directory ────────────────────────
+if [ -z "${BE_SRC:-}" ]; then
+  for candidate in backend be-* server api apps/api apps/backend; do
+    if [ -d "$REPO_ROOT/$candidate/src" ]; then
+      BE_SRC="$REPO_ROOT/$candidate/src"
+      break
+    fi
+  done
+fi
+
+if [ -z "${BE_SRC:-}" ]; then
+  echo "  [error] No backend src directory found. Set BE_SRC env var."
+  exit 1
+fi
+
+MODULE_NAME="${1:?Usage: check-module.sh <module-name>}"
+
+# Try to find the module directory
+MODULE_DIR=""
+for candidate in "$BE_SRC/features/$MODULE_NAME" "$BE_SRC/core/$MODULE_NAME"; do
+  if [ -d "$candidate" ]; then
+    MODULE_DIR="$candidate"
+    break
+  fi
+done
+
+if [ -z "$MODULE_DIR" ]; then
+  echo "  [error] Module '$MODULE_NAME' not found in features/ or core/"
+  echo "  Available feature modules:"
+  ls -1 "$BE_SRC/features/" 2>/dev/null | sed 's/^/    /'
+  exit 1
+fi
+
+echo ""
+echo "  ╔══════════════════════════════════════╗"
+echo "  ║  Module Health Check: $MODULE_NAME"
+echo "  ║  Path: ${MODULE_DIR#$REPO_ROOT/}"
+echo "  ╚══════════════════════════════════════╝"
+echo ""
+
+ISSUES=0
+WARNINGS=0
+
+check() {
+  local label="$1" result="$2"
+  if [ "$result" == "pass" ]; then
+    echo "  ✓  $label"
+  elif [ "$result" == "warn" ]; then
+    echo "  ⚠  $label"
+    WARNINGS=$((WARNINGS + 1))
+  else
+    echo "  ✗  $label"
+    ISSUES=$((ISSUES + 1))
+  fi
+}
+
+# ─── Structure Checks ────────────────────────────────────────
+echo "  Structure:"
+
+# Module file
+if find "$MODULE_DIR" -name "*.module.ts" | grep -q .; then
+  check "Has module.ts" "pass"
+else
+  check "Missing module.ts" "fail"
+fi
+
+# Controller
+if find "$MODULE_DIR" -name "*.controller.ts" | grep -q .; then
+  check "Has controller(s)" "pass"
+else
+  check "No controllers found" "warn"
+fi
+
+# Service
+if find "$MODULE_DIR" -name "*.service.ts" | grep -q .; then
+  check "Has service(s)" "pass"
+else
+  check "No services found" "warn"
+fi
+
+echo ""
+echo "  Schemas & DTOs:"
+
+# DTOs
+DTO_COUNT=$(find "$MODULE_DIR" -path "*/dto/*" -name "*.ts" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$DTO_COUNT" -gt 0 ]; then
+  check "Has DTOs ($DTO_COUNT files)" "pass"
+
+  # Check for class-validator usage
+  VALIDATED=$(grep -rl "class-validator" "$MODULE_DIR" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$VALIDATED" -gt 0 ]; then
+    check "Uses class-validator decorators" "pass"
+  else
+    check "DTOs exist but no class-validator decorators found" "warn"
+  fi
+else
+  check "No DTO directory" "warn"
+fi
+
+# Entities/Schemas
+ENTITY_COUNT=$(find "$MODULE_DIR" -path "*/entities/*" -name "*.ts" 2>/dev/null | wc -l | tr -d ' ')
+SCHEMA_COUNT=$(grep -rl "@Schema" "$MODULE_DIR" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$ENTITY_COUNT" -gt 0 ] || [ "$SCHEMA_COUNT" -gt 0 ]; then
+  check "Has Mongoose schemas ($ENTITY_COUNT entity files, $SCHEMA_COUNT @Schema)" "pass"
+
+  # Check for indexes
+  INDEX_COUNT=$(grep -r "@Index\|index: true" "$MODULE_DIR" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$INDEX_COUNT" -gt 0 ]; then
+    check "Has database indexes ($INDEX_COUNT)" "pass"
+  else
+    check "No @Index or index:true found — may need indexes for query performance" "warn"
+  fi
+else
+  check "No entity/schema files" "warn"
+fi
+
+echo ""
+echo "  Quality:"
+
+# Tests
+TEST_COUNT=$(find "$MODULE_DIR" -name "*.spec.ts" -o -name "*.test.ts" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$TEST_COUNT" -gt 0 ]; then
+  check "Has tests ($TEST_COUNT files)" "pass"
+else
+  check "No test files found" "warn"
+fi
+
+# Swagger decorators
+SWAGGER_COUNT=$(grep -r "@ApiTags\|@ApiOperation\|@ApiResponse" "$MODULE_DIR" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$SWAGGER_COUNT" -gt 0 ]; then
+  check "Has Swagger docs ($SWAGGER_COUNT decorators)" "pass"
+else
+  check "No Swagger decorators found" "warn"
+fi
+
+# Auth guards
+GUARD_COUNT=$(grep -r "UseGuards\|JwtAuthGuard\|AuthGuard" "$MODULE_DIR" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$GUARD_COUNT" -gt 0 ]; then
+  check "Uses auth guards ($GUARD_COUNT)" "pass"
+else
+  check "No auth guards found — are all endpoints public?" "warn"
+fi
+
+# any usage
+ANY_COUNT=$(grep -r ": any\b" "$MODULE_DIR" --include="*.ts" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$ANY_COUNT" -lt 5 ]; then
+  check "Low 'any' usage ($ANY_COUNT occurrences)" "pass"
+elif [ "$ANY_COUNT" -lt 20 ]; then
+  check "'any' type used $ANY_COUNT times — consider adding proper types" "warn"
+else
+  check "High 'any' usage ($ANY_COUNT occurrences) — needs typing improvement" "fail"
+fi
+
+# Error handling
+TRY_CATCH=$(grep -r "try {" "$MODULE_DIR" --include="*.ts" 2>/dev/null | wc -l | tr -d ' ')
+THROWS=$(grep -r "throw new" "$MODULE_DIR" --include="*.ts" 2>/dev/null | wc -l | tr -d ' ')
+check "Error handling: $TRY_CATCH try/catch blocks, $THROWS throw statements" "pass"
+
+# File count
+TS_COUNT=$(find "$MODULE_DIR" -name "*.ts" | wc -l | tr -d ' ')
+
+echo ""
+echo "  ════════════════════════════════════"
+echo "  Summary: $TS_COUNT TypeScript files"
+echo "  Issues: $ISSUES | Warnings: $WARNINGS"
+if [ $ISSUES -gt 0 ]; then
+  echo "  Status: NEEDS ATTENTION"
+  exit 1
+elif [ $WARNINGS -gt 3 ]; then
+  echo "  Status: FAIR — several areas for improvement"
+else
+  echo "  Status: GOOD"
+fi
+echo ""