@jaysonder/tts-server 1.0.0

package/.env.example

@@ -0,0 +1,10 @@
+OPENAI_API_KEY=your-openai-api-key-here
+
+# GCP
+PROJECT_ID=your-gcp-project-id-here
+REGION=your-gcp-region-here
+SERVICE_NAME=your-service-name-here
+CLIENT_URL=your-client-url-here # e.g., http://localhost:5173 or https://yourdomain.com
+
+# Port (automatically set by Cloud Run, default: 8080)
+PORT=8080

package/.github/workflows/publish-validation.yml

@@ -0,0 +1,49 @@
+name: Publish Validation Package
+
+on:
+  push:
+    tags:
+      - 'validation-v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: packages/validation
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: npm
+          cache-dependency-path: packages/validation/package-lock.json
+
+      - name: Install package dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Ensure tag matches package version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          package_version=$(node -p "require('./package.json').version")
+          tag_version="${GITHUB_REF_NAME#validation-v}"
+
+          if [ "$package_version" != "$tag_version" ]; then
+            echo "Tag version $tag_version does not match package version $package_version"
+            exit 1
+          fi
+
+      - name: Publish package to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 120,
+  "tabWidth": 2
+}

package/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md — NestJS Standards
+
+## Project Structure
+```
+src/
+├── main.ts                    # Entry point
+├── app.module.ts              # Root module
+├── common/
+│   ├── types/index.ts       # Shared types
+│   └── utils/               # Logger, validation, rate-limiter, room-code
+└── game/
+    ├── game.module.ts        # Feature module
+    ├── game.gateway.ts       # WebSocket gateway
+    ├── game.controller.ts    # REST controller
+    ├── dto/                 # DTOs (use class-validator)
+    └── services/            # GameEngine, RoomManager, TwisterGenerator, Scoring
+```
+
+## Conventions
+- **ESM**: Use `.js` extensions in all imports
+- **Decorators**: `@WebSocketGateway`, `@SubscribeMessage`, `@MessageBody`, `@Controller`, `@Get`, `@Post`
+- **Validation**: class-validator decorators on DTOs; custom `validateDto()` for WebSocket payloads
+- **DI**: Constructor injection with `@Injectable()` for all services
+- **Naming**: PascalCase (classes), camelCase (variables/functions)
+- **Error handling**: Throw `HttpException`/`BadRequestException` for HTTP errors
+
+## Commands
+| Action    | Command           |
+|-----------|-------------------|
+| Dev       | `npm run dev`     |
+| Build     | `npm run build`   |
+| Start     | `npm run start`   |
+| Lint      | `npm run lint`    |
+
+## Environment
+| Variable        | Required | Default     |
+|-----------------|----------|-------------|
+| OPENAI_API_KEY  | Yes      | -           |
+| CLIENT_URL      | Yes      | -           |
+| PORT            | No       | 3001        |
+| LOG_LEVEL       | No       | info        |

package/Dockerfile

@@ -0,0 +1,22 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install all dependencies (including dev for TypeScript build)
+RUN npm ci
+
+# Copy source files
+COPY src/ ./src/
+
+# Build TypeScript
+RUN npm run build
+
+# Expose port (Cloud Run uses PORT env var)
+EXPOSE 8080
+
+# Start the server
+CMD ["node", "dist/index.js"]

package/README.md

@@ -0,0 +1,61 @@
+# Tone TTS Server
+
+Multiplayer tongue twister game server. Players create/join rooms, compete to say tongue twisters, and get scored on speech accuracy.
+
+## Client Connections
+
+| Type | Protocol | Purpose |
+|------|----------|---------|
+| **REST API** | HTTP | Generate tongue twisters, query lobby stats (`/api/*`) |
+| **WebSocket** | Socket.IO | Real-time multiplayer — room management, game state, answer submission |
+
+### Socket.IO Events
+
+**Client → Server:** `create-room`, `join-room`, `start-game`, `submit-answer`, `pause-game`, `resume-game`, `get-room-state`
+
+**Server → Client:** `player-joined`, `player-left`, `game-started`, `round-advanced`, `player-submitted`, `game-paused`, `game-resumed`, `round-time-expired`, `game-ended`
+
+## Commands
+
+```bash
+npm run dev          # Start dev server with hot reload
+npm run build        # Compile TypeScript
+npm start            # Run compiled build
+npm run lint         # Lint source files
+npm run lint:fix     # Auto-fix lint issues
+npm run format       # Format with Prettier
+npm run format:check # Check formatting
+npm run typecheck    # Type-check without emitting
+npm test             # Run tests
+```
+
+## Environment
+
+Copy `.env.example` to `.env` and set:
+
+- `OPENAI_API_KEY` — OpenAI API key for generating tongue twisters
+- `CLIENT_URL` — Allowed CORS origin (e.g. `http://localhost:5173`)
+- `PORT` — Server port (default `8080`)
+
+## Deploy
+
+```bash
+./deploy-to-gcp.sh
+```
+
+## Publish Validation Package
+
+The shared validation package for the UI is published to npm as `@nemsae/tts-validation`.
+
+Before publishing:
+
+1. Update the version in `packages/validation/package.json`.
+2. Refresh `packages/validation/package-lock.json` with `npm --prefix packages/validation install --package-lock-only`.
+3. Merge the version bump to `main`.
+4. Create and push a matching tag like `validation-v0.1.0`.
+
+The `Publish Validation Package` GitHub Actions workflow will publish `packages/validation` to npm using the repo `NPM_TOKEN` secret. After that, other repos can install it with:
+
+```bash
+npm install @nemsae/tts-validation zod
+```

package/deploy-to-gcp.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+
+# GCP Deployment Script for TTS Server
+# Replace these variables with your values
+PROJECT_ID="project-id"  # Replace with your GCP project ID
+REGION="us-central1"          # Change if you prefer a different region
+SERVICE_NAME="tts-server"
+CLIENT_URL="client-url"  # Replace with your frontend URL
+
+if [ -f .env ]; then
+    source .env
+    OPENAI_KEY=$OPENAI_API_KEY
+    REGION=$REGION
+    SERVICE_NAME=$SERVICE_NAME
+    CLIENT_URL=$CLIENT_URL
+    PROJECT_ID=$PROJECT_ID
+else
+    echo -e "${YELLOW}Warning: .env file not found. Please set the required environment variables.${NC}"
+fi
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}Starting GCP deployment for TTS Server...${NC}"
+
+# Check if gcloud is installed
+if ! command -v gcloud &> /dev/null; then
+    echo -e "${RED}Error: gcloud CLI is not installed.${NC}"
+    echo "Please install Google Cloud SDK: https://cloud.google.com/sdk/docs/install"
+    exit 1
+fi
+
+# Check if user is authenticated
+if ! gcloud auth list --filter=status:ACTIVE --format="value(account)" &> /dev/null; then
+    echo -e "${YELLOW}You need to authenticate with GCP.${NC}"
+    gcloud auth login
+fi
+
+# Set the project
+echo -e "${GREEN}Setting project to: ${PROJECT_ID}${NC}"
+gcloud config set project $PROJECT_ID
+
+# Enable required APIs
+echo -e "${GREEN}Enabling required APIs...${NC}"
+gcloud services enable run.googleapis.com
+gcloud services enable cloudbuild.googleapis.com
+gcloud services enable secretmanager.googleapis.com
+
+# Create secrets
+echo -e "${GREEN}Creating secrets in Secret Manager...${NC}"
+
+# Create secret for OpenAI API key
+if ! gcloud secrets describe openai-api-key &> /dev/null; then
+    printf '%s' "$OPENAI_KEY" | gcloud secrets create openai-api-key --data-file=-
+    echo -e "${GREEN}Created openai-api-key secret${NC}"
+else
+    printf '%s' "$OPENAI_KEY" | gcloud secrets versions add openai-api-key --data-file=-
+    echo -e "${GREEN}Updated openai-api-key secret${NC}"
+fi
+
+# Create secret for frontend URL
+if ! gcloud secrets describe client-url &> /dev/null; then
+    printf '%s' "$CLIENT_URL" | gcloud secrets create client-url --data-file=-
+    echo -e "${GREEN}Created client-url secret${NC}"
+else
+    printf '%s' "$CLIENT_URL" | gcloud secrets versions add client-url --data-file=-
+    echo -e "${GREEN}Updated client-url secret${NC}"
+fi
+
+# Build and push the container
+echo -e "${GREEN}Building and pushing container image...${NC}"
+IMAGE_TAG="gcr.io/${PROJECT_ID}/${SERVICE_NAME}:latest"
+gcloud builds submit --tag $IMAGE_TAG .
+
+# Deploy to Cloud Run
+echo -e "${GREEN}Deploying to Cloud Run...${NC}"
+gcloud run deploy $SERVICE_NAME \
+  --image=$IMAGE_TAG \
+  --region=$REGION \
+  --platform=managed \
+  --allow-unauthenticated \
+  --port=8080 \
+  --timeout=3600 \
+  --session-affinity \
+  --min-instances=1 \
+  --max-instances=10 \
+  --memory=512Mi \
+  --cpu=1 \
+  --set-secrets="OPENAI_API_KEY=openai-api-key:latest,CLIENT_URL=client-url:latest"
+
+# Get the service URL
+SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --region=$REGION --format="value(status.url)")
+
+echo -e "${GREEN}Deployment complete!${NC}"
+echo -e "Your service is available at: ${YELLOW}${SERVICE_URL}${NC}"
+echo -e "Update your frontend to connect to: ${YELLOW}${SERVICE_URL}${NC}"
+
+# Test the deployment
+echo -e "${GREEN}Testing deployment...${NC}"
+curl -s -o /dev/null -w "%{http_code}" $SERVICE_URL || echo "Service might still be starting up..."
+
+echo -e "\n${GREEN}Deployment script completed!${NC}"

package/eslint.config.js

@@ -0,0 +1,30 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default tseslint.config(
+  {
+    ignores: ['dist/'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    files: ['**/*.js'],
+    ...tseslint.configs.disableTypeChecked,
+  },
+  eslintConfigPrettier,
+  {
+    rules: {
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-misused-promises': ['error', { checksVoidReturn: { attributes: false } }],
+    },
+  },
+);

package/nest-cli.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true,
+    "assets": ["**/*.env"],
+    "watchAssets": true
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jaysonder/tts-server",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "nest start --watch",
+    "prebuild": "npm run build:validation",
+    "build:validation": "tsc -p packages/validation/tsconfig.json",
+    "publish:validation": "npm --prefix packages/validation publish --access=public",
+    "bump:validation:patch": "npm --prefix packages/validation version patch",
+    "bump:validation:minor": "npm --prefix packages/validation version minor",
+    "bump:validation:major": "npm --prefix packages/validation version major",
+    "build": "nest build",
+    "start": "node dist/main",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@jaysonder/tts-validation": "file:packages/validation",
+    "@nestjs/common": "^10.4.15",
+    "@nestjs/config": "^3.3.0",
+    "@nestjs/core": "^10.4.15",
+    "@nestjs/platform-express": "^10.4.15",
+    "@nestjs/platform-socket.io": "^10.4.15",
+    "@nestjs/websockets": "^10.4.15",
+    "cors": "^2.8.6",
+    "dotenv": "^17.3.1",
+    "openai": "^6.22.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "socket.io": "^4.7.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@nestjs/cli": "^10.4.9",
+    "@nestjs/schematics": "^10.2.3",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.58.0",
+    "zod": "^4.3.6"
+  }
+}

package/packages/validation/README.md

@@ -0,0 +1,25 @@
+# @nemsae/tts-validation
+
+Shared Zod schemas and inferred types for the Tone TTS server and UI.
+
+## Install
+
+```bash
+npm install @nemsae/tts-validation zod
+```
+
+## Usage
+
+```ts
+import { CreateRoomSchema } from '@nemsae/tts-validation';
+
+const result = CreateRoomSchema.safeParse(formValues);
+
+if (!result.success) {
+  console.log(result.error.flatten());
+}
+```
+
+## Publishing
+
+This package is published from the main server repo via the `Publish Validation Package` GitHub Actions workflow.

package/packages/validation/package-lock.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nemsae/tts-validation",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@nemsae/tts-validation",
+      "version": "0.1.0",
+      "license": "MIT",
+      "devDependencies": {
+        "typescript": "^5.0.0",
+        "zod": "^4.3.6"
+      },
+      "peerDependencies": {
+        "zod": "^4.0.0"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.3.6",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
+      "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
+      "dev": true,
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/packages/validation/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jaysonder/tts-validation",
+  "version": "0.1.0",
+  "description": "Shared Zod validation schemas for TTS",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "zod": "^4.3.6"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nemsae/tts-server.git",
+    "directory": "packages/validation"
+  },
+  "homepage": "https://github.com/nemsae/tts-server/tree/main/packages/validation",
+  "bugs": {
+    "url": "https://github.com/nemsae/tts-server/issues"
+  },
+  "keywords": [
+    "tts",
+    "validation",
+    "zod",
+    "schemas"
+  ]
+}

package/packages/validation/src/index.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { sanitizeInput, checkTopicForInjection } from './validation-helpers.js';
+
+// ── Constants ──────────────────────────────────────────────────────────
+export const MAX_TOPIC_LENGTH = 80;
+export const MAX_ROUNDS = 10;
+export const MAX_CUSTOM_LENGTH = 20;
+export const MAX_PLAYER_NAME_LENGTH = 20;
+export const MAX_TRANSCRIPT_LENGTH = 500;
+export const MIN_ROUND_TIME_LIMIT = 5;
+export const MAX_ROUND_TIME_LIMIT = 120;
+
+// ── Reusable field schemas ─────────────────────────────────────────────
+
+export const TwisterLengthSchema = z.enum(['short', 'medium', 'long', 'custom']);
+
+export const TopicSchema = z
+  .string()
+  .min(1, 'Topic cannot be empty')
+  .transform((val) => sanitizeInput(val))
+  .pipe(
+    z
+      .string()
+      .min(1, 'Topic cannot be empty after sanitization')
+      .max(MAX_TOPIC_LENGTH, `Topic exceeds maximum length of ${MAX_TOPIC_LENGTH} characters`)
+      .superRefine((val, ctx) => {
+        const injectionError = checkTopicForInjection(val);
+        if (injectionError) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message: injectionError });
+        }
+      }),
+  );
+
+export const RoundsSchema = z
+  .number()
+  .int('Rounds must be an integer')
+  .min(1, 'Rounds must be at least 1')
+  .max(MAX_ROUNDS, `Rounds cannot exceed ${MAX_ROUNDS}`);
+
+export const CustomLengthSchema = z
+  .number()
+  .int('Custom length must be an integer')
+  .min(1, 'Custom length must be at least 1 word')
+  .max(MAX_CUSTOM_LENGTH, `Custom length cannot exceed ${MAX_CUSTOM_LENGTH} words`);
+
+export const PlayerNameSchema = z
+  .string()
+  .min(1, 'Player name cannot be empty')
+  .transform((val) => {
+    let sanitized = val.replace(/<[^>]*>/g, '').trim();
+    sanitized = sanitized.replace(/\s+/g, ' ').trim();
+    return sanitized;
+  })
+  .pipe(
+    z
+      .string()
+      .min(1, 'Player name cannot be empty')
+      .max(MAX_PLAYER_NAME_LENGTH, `Player name exceeds maximum length of ${MAX_PLAYER_NAME_LENGTH} characters`),
+  );
+
+export const TranscriptSchema = z
+  .string()
+  .min(1, 'Transcript cannot be empty')
+  .transform((val) => {
+    // eslint-disable-next-line no-control-regex
+    const controlChars = new RegExp('[\\x00-\\x1F\\x7F]', 'g');
+    let sanitized = val.replace(controlChars, '').replace(/\s+/g, ' ').trim();
+    if (sanitized.length > MAX_TRANSCRIPT_LENGTH) {
+      sanitized = sanitized.slice(0, MAX_TRANSCRIPT_LENGTH);
+    }
+    return sanitized;
+  })
+  .pipe(z.string().min(1, 'Transcript cannot be empty'));
+
+// ── Composite schemas (DTOs) ──────────────────────────────────────────
+
+export const GameSettingsSchema = z.object({
+  topic: TopicSchema,
+  length: TwisterLengthSchema,
+  customLength: CustomLengthSchema.optional(),
+  rounds: RoundsSchema,
+  roundTimeLimit: z.number().min(MIN_ROUND_TIME_LIMIT, `Round time limit must be at least ${MIN_ROUND_TIME_LIMIT} seconds`).max(MAX_ROUND_TIME_LIMIT, `Round time limit cannot exceed ${MAX_ROUND_TIME_LIMIT} seconds`),
+  autoSubmitEnabled: z.boolean().optional(),
+  autoSubmitDelay: z.number().optional(),
+});
+
+export const CreateRoomSchema = z.object({
+  playerName: PlayerNameSchema,
+  settings: GameSettingsSchema,
+});
+
+export const JoinRoomSchema = z.object({
+  roomCode: z.string().min(1, 'Room code is required'),
+  playerName: PlayerNameSchema,
+});
+
+export const SubmitAnswerSchema = z.object({
+  transcript: TranscriptSchema,
+  timestamp: z.number(),
+});
+
+export const GenerateTwistersSchema = z.object({
+  topic: TopicSchema,
+  length: TwisterLengthSchema,
+  customLength: CustomLengthSchema.optional(),
+  rounds: RoundsSchema.optional(),
+});
+
+// ── Inferred types ────────────────────────────────────────────────────
+
+export type TwisterLength = z.infer<typeof TwisterLengthSchema>;
+export type GameSettings = z.infer<typeof GameSettingsSchema>;
+export type CreateRoomDto = z.infer<typeof CreateRoomSchema>;
+export type JoinRoomDto = z.infer<typeof JoinRoomSchema>;
+export type SubmitAnswerDto = z.infer<typeof SubmitAnswerSchema>;
+export type GenerateTwistersDto = z.infer<typeof GenerateTwistersSchema>;
+
+// ── Re-export helpers ─────────────────────────────────────────────────
+
+export { sanitizeInput, checkTopicForInjection } from './validation-helpers.js';