# dev-scripts Specification

## Purpose
TBD - created by archiving change add-dev-scripts. Update Purpose after archive.
## Requirements
### Requirement: Environment Validation
The check-env script SHALL validate all prerequisites required to run the development environment.

#### Scenario: Check Python version
- **WHEN** the check-env script runs
- **THEN** the system SHALL:
  - Verify Python 3.10 or higher is installed
  - Display the detected Python version
  - Exit with error if Python version is insufficient

#### Scenario: Check Node.js and npm
- **WHEN** the check-env script runs
- **THEN** the system SHALL:
  - Verify Node.js is installed (v18+ recommended)
  - Verify npm is available
  - Display detected versions

#### Scenario: Check Docker availability
- **WHEN** the check-env script runs
- **THEN** the system SHALL:
  - Verify Docker daemon is running
  - Verify docker-compose is available
  - Display Docker version

#### Scenario: Check virtual environment
- **WHEN** the check-env script runs
- **THEN** the system SHALL:
  - Verify venv/ directory exists
  - Suggest creation command if missing: `python -m venv venv`

#### Scenario: Check environment file
- **WHEN** the check-env script runs
- **THEN** the system SHALL:
  - Verify .env file exists
  - Suggest copying from .env.example if missing
  - Warn if critical variables appear empty (FERNET_KEY)

#### Scenario: Check port availability
- **WHEN** the check-env script runs
- **THEN** the system SHALL:
  - Check if ports 8000, 3000, 9000, 9001 are available
  - Display which ports are in use and by what process
  - Warn but continue if ports are occupied

### Requirement: Development Server Startup
The start-dev script SHALL orchestrate the startup of all development services in the correct order.

#### Scenario: Pre-flight validation
- **WHEN** the start-dev script runs
- **THEN** the system SHALL:
  - Execute check-env.sh first
  - Abort startup if critical checks fail

#### Scenario: Start MinIO
- **WHEN** start-dev begins service startup
- **THEN** the system SHALL:
  - Start MinIO using docker-compose -f docker-compose.minio.yml up -d
  - Wait for MinIO health check to pass (up to 30 seconds)
  - Display MinIO console URL (http://localhost:9001)

#### Scenario: Start backend server
- **WHEN** MinIO is healthy
- **THEN** the system SHALL:
  - Activate the virtual environment
  - Install/update requirements if requirements.txt is newer than last install
  - Start uvicorn in background: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
  - Wait for backend to respond (up to 15 seconds)
  - Display backend URL (http://localhost:8000)

#### Scenario: Start frontend dev server
- **WHEN** backend is healthy
- **THEN** the system SHALL:
  - Check if node_modules exists, run npm install if missing
  - Start frontend dev server: npm run dev
  - Display frontend URL (http://localhost:3000)

#### Scenario: Display startup summary
- **WHEN** all services are running
- **THEN** the system SHALL:
  - Display summary table with all service URLs
  - Display log file locations
  - Display instructions for stopping services

#### Scenario: Handle graceful shutdown
- **WHEN** user presses Ctrl+C during startup or operation
- **THEN** the system SHALL:
  - Trap the SIGINT signal
  - Execute stop-dev.sh to clean up
  - Display shutdown confirmation

### Requirement: Development Server Shutdown
The stop-dev script SHALL gracefully terminate all development services.

#### Scenario: Stop frontend server
- **WHEN** stop-dev script runs
- **THEN** the system SHALL:
  - Find and terminate the Vite dev server process
  - Confirm termination or report if not running

#### Scenario: Stop backend server
- **WHEN** stop-dev script runs
- **THEN** the system SHALL:
  - Find and terminate the uvicorn process
  - Confirm termination or report if not running

#### Scenario: Stop MinIO
- **WHEN** stop-dev script runs
- **THEN** the system SHALL:
  - Run docker-compose -f docker-compose.minio.yml down
  - Preserve data volumes (do not use -v flag)
  - Confirm MinIO container stopped

#### Scenario: Display shutdown summary
- **WHEN** all services are stopped
- **THEN** the system SHALL:
  - Display confirmation message for each service
  - Report any services that failed to stop