feat(api): add terminal WebSocket gateway with PTY session management (#515)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

apps/api/src/terminal/terminal.dto.ts

@@ -0,0 +1,89 @@
+/**
+ * Terminal DTOs
+ *
+ * Data Transfer Objects for terminal WebSocket events.
+ * Validated using class-validator decorators.
+ */
+
+import {
+  IsString,
+  IsOptional,
+  IsNumber,
+  IsInt,
+  Min,
+  Max,
+  MinLength,
+  MaxLength,
+} from "class-validator";
+
+/**
+ * DTO for creating a new terminal PTY session.
+ */
+export class CreateTerminalDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(128)
+  name?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(500)
+  cols?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  rows?: number;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(4096)
+  cwd?: string;
+}
+
+/**
+ * DTO for sending input data to a terminal PTY session.
+ */
+export class TerminalInputDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(64)
+  sessionId!: string;
+
+  @IsString()
+  data!: string;
+}
+
+/**
+ * DTO for resizing a terminal PTY session.
+ */
+export class TerminalResizeDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(64)
+  sessionId!: string;
+
+  @IsNumber()
+  @IsInt()
+  @Min(1)
+  @Max(500)
+  cols!: number;
+
+  @IsNumber()
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  rows!: number;
+}
+
+/**
+ * DTO for closing a terminal PTY session.
+ */
+export class CloseTerminalDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(64)
+  sessionId!: string;
+}