feat: Fullstack Development Server with Health Checks and Graceful Shutdown

[jejernig]

Summary

Implements single-command startup for both Next.js frontend and Express backend with automatic port detection, health monitoring, and comprehensive test coverage.

Features

• ✅ Single Command Startup: npm run dev:fullstack starts both services
• ✅ Automatic Port Detection: Backend finds available port in range 3401-3410
• ✅ Health Checks: Startup script verifies backend readiness
• ✅ Graceful Shutdown: Clean process termination with no orphans
• ✅ Hot Reload: Frontend Fast Refresh + backend auto-restart (~100ms)
• ✅ Colored Output: Service-specific prefixes (blue/green)

Implementation Details

Scripts Created:

• scripts/find-port.js - Port detection utility
• scripts/health-check.js - Health check polling
• scripts/start-backend.js - Backend orchestrator

Backend Server:

• server/src/index.ts - Express server with health endpoint
• server/src/config/port.ts - Port configuration module

Dependencies Added:

• express@^4.21.2
• concurrently@^9.2.1 (dev)
• get-port@^7.1.0 (dev)
• tsx@^4.20.6 (dev)
• @types/express@^4.17.23 (dev)

Test Coverage

Unit Tests: 35 test cases

• Port detection logic (9 tests)
• Health check polling (15 tests)
• Backend startup (11 tests)

E2E Tests: 11 scenarios

• Startup flow
• Health checks
• Graceful shutdown
• Port conflicts
• Error handling

See TESTING_FULLSTACK_SERVER.md for complete testing documentation.

Documentation

• ✅ README.md updated with "Development Server" section
• ✅ All scripts have JSDoc documentation
• ✅ Comprehensive testing guide created
• ✅ Troubleshooting section included

Validation

• ✅ Manual testing passed on macOS
• ✅ Type checking passes (npm run type-check)
• ✅ Linting passes (no new errors)
• ✅ E2E tests ready to run

User Stories Delivered

• ✅ US1 (P1): Single command startup
• ✅ US2 (P2): Health checks and status visibility
• ✅ US3 (P3): Graceful shutdown

Breaking Changes

None. This is a new feature that doesn't affect existing functionality.

Usage

# Start both services
npm run dev:fullstack

# Or individually
npm run dev:frontend  # Port 3060
npm run dev:backend   # Auto-detected port 3401-3410

Testing

# Run E2E tests
npm run test:e2e tests/e2e/fullstack-server.spec.ts

# Run smoke tests
npm run test:e2e tests/e2e/fullstack-server.spec.ts --grep "@smoke"

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Fullstack dev server: single command to start frontend and backend with hot reload, colored logs, and health checks.
  • Backend server with /health endpoint, graceful shutdown, and automatic port selection within a configurable range.
  • Environment template for local configuration (ports, log level, type-checking), plus watch-mode type checking.

• Documentation

  • Expanded setup and troubleshooting guidance for development, environment variables, testing, and deployment.
  • New guide detailing test coverage and execution.

• Tests

  • Added unit tests for port discovery, health checks, and backend startup.
  • Added E2E tests covering startup, health, graceful shutdown, port conflicts, and output formatting.
  • Updated test configuration.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Adds a fullstack dev workflow: backend server (Express) with health endpoint, port config, startup orchestration scripts (find available port, health polling, start backend), environment template, npm scripts, Jest setup, and comprehensive unit/E2E tests. Documentation expanded for dev server usage, testing, troubleshooting, and environment configuration.

Changes

Cohort / File(s)	Summary
Documentation README.md, TESTING_FULLSTACK_SERVER.md, .env.local.template	Adds dev server usage, env setup, scripts, troubleshooting, testing guidance; introduces env template with backend port range, frontend port, log level, and type-check toggle.
Jest Config & Setup jest.config.cjs, jest.setup.cjs	Points setupFilesAfterEnv to CommonJS setup, adds testMatch for scripts/__tests__/**, switches jest-dom import to require, keeps IntersectionObserver mock.
Package Manifests package.json, server/package.json	Enables ESM ("type":"module"), adds dev scripts (dev:frontend, dev:backend, dev:fullstack), type-check watch, dependencies (express, tsx, get-port, concurrently, types). Adds backend package metadata.
Backend Scripts (orchestration) scripts/find-port.js, scripts/health-check.js, scripts/start-backend.js	New Node scripts to compute/validate port range, find first free port, poll /health, validate Node version/files, spawn tsx server with env, forward signals, and manage lifecycle. Export utility functions for tests.
Script Unit Tests scripts/__tests__/* → find-port.test.js, health-check.test.js, start-backend.test.js	Adds comprehensive tests for port parsing/selection, health request/polling with timers and HTTP mocks, backend startup validations, process spawning, and logging/error paths.
Backend Server server/src/config/port.ts, server/src/index.ts	Introduces port config loader/validator and Express server with /health, root route, 404 and error handlers, startup on 127.0.0.1, graceful shutdown, and exported app/startServer.
E2E Tests tests/e2e/fullstack-server.spec.ts	Playwright E2E for fullstack startup, health readiness, colored output, graceful shutdown, port conflicts, failure handling, and basic hot reload behavior.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Dev as Developer
  participant SB as scripts/start-backend.js
  participant FP as scripts/find-port.js
  participant BE as Backend (server/src/index.ts)
  participant HC as scripts/health-check.js

  Dev->>SB: Run dev:backend (npm)
  SB->>SB: validateNodeVersion + validateBackendFiles
  SB->>FP: spawn find-port (range from env/CLI/defaults)
  FP-->>SB: stdout: first available port or error
  SB->>BE: spawn tsx watch with PORT, NODE_ENV
  SB->>HC: pollHealth(PORT)
  HC->>BE: GET /health
  BE-->>HC: 200 {"health":{"status":"ok"}}
  HC-->>SB: Healthy
  SB-->>Dev: Backend ready (logs)

  Note over SB,BE: On SIGINT/SIGTERM, forward signal and exit on child close

Loading

sequenceDiagram
  autonumber
  participant Client as Client
  participant BE as Backend (Express)
  participant Cfg as port.ts

  Client->>BE: GET /health
  BE->>BE: uptime, timestamp
  BE-->>Client: 200 {status:"ok",port,uptime,timestamp}

  Client->>BE: GET /
  BE-->>Client: 200 {name,version,healthUrl}

  BE->>Cfg: loadPortConfig()
  Cfg-->>BE: {port,portRangeStart,portRangeEnd}
  BE->>BE: listen(127.0.0.1, port)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

Thump-thump goes my coder heart,
I sniffed a port and claimed my part. 🐇
Health says “ok,” logs glow bright,
Watch-mode hums through day and night.
Docs in paws, tests in bloom—
Fullstack fields now have more room. ✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 001-fullstack-dev-server

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d3cbfea and 8886786.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (16)

• .env.local.template (1 hunks)
• README.md (1 hunks)
• TESTING_FULLSTACK_SERVER.md (1 hunks)
• jest.config.cjs (2 hunks)
• jest.setup.cjs (1 hunks)
• package.json (6 hunks)
• scripts/__tests__/find-port.test.js (1 hunks)
• scripts/__tests__/health-check.test.js (1 hunks)
• scripts/__tests__/start-backend.test.js (1 hunks)
• scripts/find-port.js (1 hunks)
• scripts/health-check.js (1 hunks)
• scripts/start-backend.js (1 hunks)
• server/package.json (1 hunks)
• server/src/config/port.ts (1 hunks)
• server/src/index.ts (1 hunks)
• tests/e2e/fullstack-server.spec.ts (1 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}