Merge branch 'develop' into pr/plg-monitoring-stack

Author: alex-struk

.github/workflows/build-instance-images.yml

@@ -8,6 +8,9 @@ on:
         required: false
         type: string
 
+permissions:
+  contents: read
+
 jobs:
   metadata:
     name: Prepare Build Metadata

CLAUDE.md

@@ -5,4 +5,5 @@
 - Do not create features that are not explicitly described in specifications, if there is a gap, include it summary notes after implementing the task. If there is a question regarding the implementation, do not make assumptions, stop and clarify from the user.
 - When creating or modifying features, create/update documentation in /docs-md folder
 - If you need to run `npx prisma generate`, run `npm run db:generate` from `apps/backend-services` - it's a special script that writes models into apps/temporal/src and apps/backend-services/src. Don't forget to run migrations as normal if necessary.
-- Do not include any document-specific implementation, the system is generic and must support arbitrary workloads
+- Do not include any document-specific implementation, the system is generic and must support arbitrary workloads
+- All backend controllers must have full Swagger/OpenAPI documentation: use specific decorators (`@ApiOkResponse`, `@ApiForbiddenResponse`, `@ApiUnauthorizedResponse`, `@ApiConflictResponse`, etc.) instead of generic `@ApiResponse`, create dedicated DTO classes with `@ApiProperty` decorators for all request/response shapes, and reference those DTOs via the `type` field in response decorators.

apps/backend-services/src/bootstrap/bootstrap.controller.ts

@@ -7,33 +7,39 @@ import {
   Req,
 } from "@nestjs/common";
 import {
+  ApiConflictResponse,
+  ApiForbiddenResponse,
+  ApiOkResponse,
   ApiOperation,
-  ApiResponse,
   ApiTags,
+  ApiUnauthorizedResponse,
 } from "@nestjs/swagger";
 import { Request } from "express";
-import { KeycloakSSOAuth } from "@/decorators/custom-auth-decorators";
+import { Identity } from "@/auth/identity.decorator";
 import { User } from "../auth/types";
 import { BootstrapService } from "./bootstrap.service";
+import { BootstrapResultDto, BootstrapStatusResponseDto } from "./dto";
 
 @ApiTags("Bootstrap")
 @Controller("api/bootstrap")
 export class BootstrapController {
   constructor(private readonly bootstrapService: BootstrapService) {}
 
   @ApiOperation({
-    summary: "Check if system bootstrap is needed and if the caller is eligible",
+    summary:
+      "Check if system bootstrap is needed and if the caller is eligible",
   })
-  @ApiResponse({
-    status: 200,
+  @ApiOkResponse({
+    type: BootstrapStatusResponseDto,
     description:
       "Returns whether bootstrap is needed and whether the caller is eligible.",
   })
-  @KeycloakSSOAuth()
+  @ApiUnauthorizedResponse({ description: "User is not authenticated." })
+  @Identity()
   @Get("status")
   async getBootstrapStatus(
     @Req() req: Request & { user?: User },
-  ): Promise<{ needed: boolean; eligible: boolean }> {
+  ): Promise<BootstrapStatusResponseDto> {
     const userEmail = req.user?.email;
     return this.bootstrapService.getBootstrapStatus(userEmail);
   }
@@ -42,23 +48,22 @@ export class BootstrapController {
     summary:
       "Bootstrap the system: promote caller to admin, create Default group",
   })
-  @ApiResponse({
-    status: 200,
+  @ApiOkResponse({
+    type: BootstrapResultDto,
     description: "Bootstrap completed successfully.",
   })
-  @ApiResponse({
-    status: 403,
+  @ApiUnauthorizedResponse({ description: "User is not authenticated." })
+  @ApiForbiddenResponse({
     description: "Caller email does not match BOOTSTRAP_ADMIN_EMAIL.",
   })
-  @ApiResponse({
-    status: 409,
+  @ApiConflictResponse({
     description: "Bootstrap already completed — a system admin exists.",
   })
-  @KeycloakSSOAuth()
+  @Identity()
   @Post()
   async performBootstrap(
     @Req() req: Request & { user?: User },
-  ): Promise<{ success: boolean; groupId: string; groupName: string }> {
+  ): Promise<BootstrapResultDto> {
     const userId = req.resolvedIdentity?.userId;
     if (!userId) {
       throw new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED);

apps/backend-services/src/bootstrap/bootstrap.service.spec.ts

@@ -27,10 +27,7 @@ function createMockPrisma(adminCount = 0) {
   };
 }
 
-function createService(
-  adminCount: number,
-  bootstrapEmail: string | undefined,
-) {
+function createService(adminCount: number, bootstrapEmail: string | undefined) {
   const mockPrisma = createMockPrisma(adminCount);
   const configService = {
     get: jest.fn((key: string) => {

apps/backend-services/src/bootstrap/bootstrap.service.ts

@@ -1,8 +1,8 @@
 import { GroupRole } from "@generated/client";
 import {
+  ConflictException,
   ForbiddenException,
   Injectable,
-  ConflictException,
 } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { AuditService } from "../audit/audit.service";

apps/backend-services/src/bootstrap/dto/bootstrap-result.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from "@nestjs/swagger";
+
+export class BootstrapResultDto {
+  @ApiProperty({ description: "Whether bootstrap completed successfully" })
+  success: boolean;
+
+  @ApiProperty({ description: "ID of the created Default group" })
+  groupId: string;
+
+  @ApiProperty({ description: "Name of the created Default group" })
+  groupName: string;
+}

apps/backend-services/src/bootstrap/dto/bootstrap-status-response.dto.ts

@@ -0,0 +1,14 @@
+import { ApiProperty } from "@nestjs/swagger";
+
+export class BootstrapStatusResponseDto {
+  @ApiProperty({
+    description:
+      "Whether system bootstrap is still needed (no system admins exist)",
+  })
+  needed: boolean;
+
+  @ApiProperty({
+    description: "Whether the current caller is eligible to perform bootstrap",
+  })
+  eligible: boolean;
+}

apps/backend-services/src/bootstrap/dto/index.ts

@@ -0,0 +1,2 @@
+export { BootstrapResultDto } from "./bootstrap-result.dto";
+export { BootstrapStatusResponseDto } from "./bootstrap-status-response.dto";

apps/frontend/src/data/hooks/useBootstrap.ts

@@ -23,9 +23,7 @@ export function useBootstrapStatus(enabled: boolean) {
       const response =
         await apiService.get<BootstrapStatus>("/bootstrap/status");
       if (!response.success) {
-        throw new Error(
-          response.message ?? "Failed to check bootstrap status",
-        );
+        throw new Error(response.message ?? "Failed to check bootstrap status");
       }
       return response.data ?? { needed: false, eligible: false };
     },
@@ -41,8 +39,7 @@ export function usePerformBootstrap() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (): Promise<BootstrapResult> => {
-      const response =
-        await apiService.post<BootstrapResult>("/bootstrap", {});
+      const response = await apiService.post<BootstrapResult>("/bootstrap", {});
       if (!response.success || !response.data) {
         throw new Error(response.message ?? "Failed to perform bootstrap");
       }

apps/frontend/src/pages/RequestMembershipPage.test.tsx

@@ -24,6 +24,13 @@ vi.mock("../data/hooks/useGroups", () => ({
   useMyRequests: () => mockUseMyRequests(),
 }));
 
+vi.mock("../data/hooks/useBootstrap", () => ({
+  useBootstrapStatus: () => ({
+    data: { needed: false, eligible: false },
+    isLoading: false,
+  }),
+}));
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------