speech-synthesis-service/scripts

Platform-Integrated Service Runners

This directory contains service runners that follow the architecture patterns from the platform's @service-runners packages, providing robust service management for the speech service.

Files

platform-runner.ts

Basic orchestrator with built-in port allocation, process management, and health monitoring. This demonstrates the core patterns from the platform without requiring platform dependencies.

Usage:

tsx scripts/platform-runner.ts

Features:

• Automatic port allocation with conflict resolution
• Health monitoring for service readiness
• Coordinated lifecycle management
• Graceful shutdown handling

platform-integrated-runner.ts

Advanced runner that can detect and use platform @service-runners if available, falling back to built-in orchestration otherwise.

Usage:

tsx scripts/platform-integrated-runner.ts

Features:

• Platform runner detection
• Configuration-driven service setup
• Fallback to built-in orchestration
• Service configuration management

run-backend.ts

Standalone backend runner module following platform patterns. Can be used independently or integrated with other runners.

Usage:

# With default configuration
tsx scripts/run-backend.ts

# With custom configuration
tsx scripts/run-backend.ts --config '{"name":"my-backend","preferredPort":3000}'

Features:

• Port allocation and management
• Writes .ports.json for service discovery
• Environment variable configuration
• Watch mode with auto-restart

run-showcase.ts

Showcase UI runner that integrates with the backend service via port discovery.

Usage:

# Auto-detect backend from .ports.json
tsx scripts/run-showcase.ts

# Specify backend port explicitly
tsx scripts/run-showcase.ts --backend-port 31770

# Custom showcase port
tsx scripts/run-showcase.ts --showcase-port 5000

# Disable port file watching
tsx scripts/run-showcase.ts --no-watch

Features:

• Automatic backend discovery
• Port file monitoring
• Proxy configuration
• Change detection warnings

Integration with Platform

These runners demonstrate patterns from the platform's service management infrastructure:

From @service-runners/core:

• PortAllocator: Automatic port allocation with conflict resolution
• ProcessManager: Lifecycle management for child processes
• HealthMonitor: Service health checking and readiness detection
• ServiceRunnerCore: Base patterns for service runners

From @service-runners/vite-runner:

• Vite-specific configuration management
• Proxy setup for backend integration
• Error parsing and reporting
• Development server optimization

From @service-runners/node-runner:

• Node.js service management
• TypeScript execution with tsx
• Watch mode configuration
• Environment variable handling

Benefits

1. Robust Port Management: No more port conflicts or hardcoded ports
2. Service Coordination: Services start in correct order with health checks
3. Graceful Shutdown: Proper cleanup on exit
4. Error Handling: Structured error reporting and recovery
5. Platform Standards: Follows established patterns for consistency

Migration Path

To fully integrate with platform runners:

1. Add platform dependencies to package.json:

   {
     "devDependencies": {
       "@service-runners/core": "*",
       "@service-runners/vite-runner": "*",
       "@service-runners/node-runner": "*"
     }
   }
   

2. Update runners to import platform modules directly

3. Leverage platform error reporters and parsers

4. Use platform configuration patterns

Current vs Platform Architecture

Current (Custom Runners)

• Manual port allocation
• Basic process management
• Simple health checks
• Custom error handling

With Platform Integration

• Automatic port allocation via PortAllocator
• Robust ProcessManager with lifecycle hooks
• Advanced HealthMonitor with retry logic
• Structured ErrorReporter with framework-specific parsers

The platform integration provides production-ready service management following SOLID principles and established patterns.