Merge branch 'main' into fix/mirabel64-ba-088-090-091-096

Author: Mirabel64

.freebuff/project-id

@@ -0,0 +1 @@
+bbf909d9-9053-4c71-9421-63b2bb0139ce

.kilo/kilo.jsonc

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://app.kilo.ai/config.json",
+  "snapshot": false
+}

BackendAcademy/.env.example

@@ -3,32 +3,47 @@ PORT=3000
 NODE_ENV=development
 
 # Database
+# REQUIRED in production. Local/development uses the default below when omitted.
 DATABASE_URL=postgresql://postgres:password@localhost:5432/rustacademy
 
 # Redis
+# REQUIRED in production. Defaults to localhost in development/test.
 REDIS_HOST=localhost
 REDIS_PORT=6379
 REDIS_PASSWORD=
 
 # Auth
+# REQUIRED in production with >= 32 chars and NOT a placeholder value.
+# Development/test use explicit non-production defaults when omitted.
 JWT_SECRET=change_me_in_production
+# Maximum allowed clock skew (seconds) tolerated when verifying JWT
+# exp/nbf claims. Distributed clocks can drift, causing premature expiry
+# or acceptance of expired tokens. Bounded to 0..120 by config validation.
+JWT_CLOCK_SKEW_SECONDS=30
+
+# Signing secret for signed asset download URLs.
+# REQUIRED in production; an empty value makes signed URLs forgeable.
+ASSET_SIGNING_SECRET=change_me_in_production
 
 # API Keys
 API_KEY_SECRET=change_me_in_production
 
 # CORS
+# "*" or a comma-separated list of origins.
 CORS_ORIGIN=http://localhost:3000
 
 # AI Provider
 AI_PROVIDER=mock            # claude | openai | mock
-ANTHROPIC_API_KEY=           # Your Anthropic API key
-OPENAI_API_KEY=              # Your OpenAI API key
-AI_MODEL=                    # Model override (optional)
+ANTHROPIC_API_KEY=          # Required when AI_PROVIDER=claude
+OPENAI_API_KEY=             # Required when AI_PROVIDER=openai
+AI_MODEL=                   # Model override (optional)
 AI_MAX_TOKENS=4096
 AI_TEMPERATURE=0.7
 
 # Static & uploaded assets
 ASSETS_UPLOAD_DIR=./data/uploads  # Where uploaded assets are persisted on disk
-ASSETS_MAX_SIZE_MB=10             # Max upload size in megabytes
+ASSETS_MAX_SIZE_MB=10             # Per-file upload size limit in megabytes
+ASSETS_MAX_TOTAL_MB=1024          # Aggregate byte quota across all stored assets (MB)
+ASSETS_MAX_COUNT=10000            # Maximum number of assets retained by the registry
 ASSETS_BASE_URL=/api/v1/assets    # Base URL advertised inside asset metadata
 ASSETS_STATIC_DIR=./public        # Read-only static asset directory served at /static

BackendAcademy/BackendAcademy/src/courses/courses.module.ts

@@ -2,9 +2,20 @@ import { Module } from '@nestjs/common';
 import { CoursesController } from './courses.controller';
 import { CoursesService } from './courses.service';
 
+/**
+ * CoursesModule
+ *
+ * Groups together everything related to the "courses" feature:
+ * the controller (handles HTTP requests) and the service (business logic).
+ */
 @Module({
+  // Controllers that belong to this module and handle incoming requests
   controllers: [CoursesController],
+
+  // Providers (services) available for dependency injection within this module
   providers: [CoursesService],
+
+  // Providers exported so other modules can import and use CoursesService
   exports: [CoursesService],
 })
-export class CoursesModule {}
+export class CoursesModule {}

BackendAcademy/BackendAcademy/src/courses/courses.service.spec.ts

@@ -3,8 +3,10 @@ import { NotFoundException } from '@nestjs/common';
 import { CoursesService } from './courses.service';
 
 describe('CoursesService', () => {
+  // Holds the instance of the service under test
   let service: CoursesService;
 
+  // Runs before each test: builds a fresh testing module and resolves the service
   beforeEach(async () => {
     const module: TestingModule = await Test.createTestingModule({
       providers: [CoursesService],
@@ -13,21 +15,32 @@ describe('CoursesService', () => {
     service = module.get<CoursesService>(CoursesService);
   });
 
+  // Sanity check: the service should be instantiated correctly by the DI container
   it('should be defined', () => {
     expect(service).toBeDefined();
   });
 
+  // create() should return the submitted data merged with a generated id
   it('create() returns the dto with an id', () => {
-    const result = service.create({ title: 'Rust Basics', description: 'An intro to Rust programming language.' });
+    const result = service.create({
+      title: 'Rust Basics',
+      description: 'An intro to Rust programming language.',
+    });
+
+    // The returned object should contain the same title we passed in
     expect(result).toMatchObject({ title: 'Rust Basics' });
+
+    // An id should have been generated for the new course
     expect(result.id).toBeDefined();
   });
 
+  // findAll() should always return an array (even if empty)
   it('findAll() returns an array', () => {
     expect(Array.isArray(service.findAll())).toBe(true);
   });
 
+  // findOne() should throw a NotFoundException when the course doesn't exist
   it('findOne() throws NotFoundException for unknown id', () => {
     expect(() => service.findOne(999)).toThrow(NotFoundException);
   });
-});
+});

BackendAcademy/BackendAcademy/src/courses/courses.service.ts

@@ -2,32 +2,68 @@ import { Injectable, NotFoundException } from '@nestjs/common';
 import { CreateCourseDto } from './dto/create-course.dto';
 import { UpdateCourseDto } from './dto/update-course.dto';
 
+/**
+ * CoursesService
+ *
+ * Contains the business logic for managing courses (CRUD operations).
+ * Currently uses stub/placeholder logic; real persistence (e.g. via a
+ * repository or ORM) still needs to be implemented.
+ */
 @Injectable()
 export class CoursesService {
+  /**
+   * Creates a new course.
+   * TODO: persist the course via a repository instead of just returning it.
+   */
   create(dto: CreateCourseDto) {
     // TODO: persist via repository
+    // Temporary: fake an id using the current timestamp
     return { ...dto, id: Date.now() };
   }
 
+  /**
+   * Retrieves all courses.
+   * TODO: fetch the list from a repository/database.
+   */
   findAll() {
     // TODO: query repository
+    // Temporary: no data source yet, so return an empty array
     return [];
   }
 
+  /**
+   * Retrieves a single course by id.
+   * TODO: fetch the course from a repository/database.
+   * Throws a NotFoundException if the course doesn't exist.
+   */
   findOne(id: number) {
     // TODO: query repository
+    // Temporary: no data source yet, so this is always null
     const course = null;
+
+    // Guard clause: bail out with a 404-style error if nothing was found
     if (!course) throw new NotFoundException(`Course #${id} not found`);
+
     return course;
   }
 
+  /**
+   * Updates an existing course by id.
+   * TODO: look up the existing course, then persist the merged changes.
+   */
   update(id: number, dto: UpdateCourseDto) {
     // TODO: query then persist
+    // Temporary: just echo back the id and updated fields
     return { id, ...dto };
   }
 
+  /**
+   * Removes a course by id.
+   * TODO: actually delete the record from the repository/database.
+   */
   remove(id: number) {
     // TODO: delete from repository
+    // Temporary: just acknowledge the deletion request
     return { deleted: id };
   }
-}
+}