feat: Add development scripts for environment check and service management

- check-env.sh: Validates Python 3.10+, Node.js, Docker, venv, .env, ports - start-dev.sh: Starts MinIO, backend, frontend with health checks - stop-dev.sh: Gracefully stops all services Scripts are placed in project root for easy access. Supports --help flag and colored output. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-01 19:17:54 +08:00
parent c8966477b9
commit 77091eefb5
8 changed files with 1082 additions and 0 deletions
--- a/openspec/changes/archive/2025-12-01-add-dev-scripts/proposal.md
+++ b/openspec/changes/archive/2025-12-01-add-dev-scripts/proposal.md
@@ -0,0 +1,28 @@
+# Change: Add Development Scripts
+
+## Why
+Developers currently need to manually start multiple services (MinIO, backend, frontend) and verify environment prerequisites before running the application. This is error-prone and time-consuming. Automated scripts will streamline the development workflow and reduce onboarding friction.
+
+## What Changes
+- **NEW**: Environment check script (`check-env.sh`) - Validates all prerequisites
+- **NEW**: Unified development startup script (`start-dev.sh`) - Starts all services
+- **NEW**: Stop script (`stop-dev.sh`) - Gracefully stops all services
+
+## Impact
+- Affected specs: Creates new `dev-scripts` specification
+- Affected code:
+  - Shell scripts in project root directory
+  - No changes to existing application code
+
+## Dependencies
+- Existing docker-compose.minio.yml for MinIO
+- Python virtual environment (venv/)
+- Node.js and npm for frontend
+
+## Success Criteria
+1. `check-env.sh` validates Python 3.10+, Node.js, Docker, required ports
+2. `check-env.sh` provides clear error messages for missing prerequisites
+3. `start-dev.sh` starts MinIO, backend, and frontend in correct order
+4. `start-dev.sh` waits for each service to be healthy before proceeding
+5. `stop-dev.sh` gracefully terminates all services
+6. Scripts work on Linux/WSL environments
--- a/openspec/changes/archive/2025-12-01-add-dev-scripts/specs/dev-scripts/spec.md
+++ b/openspec/changes/archive/2025-12-01-add-dev-scripts/specs/dev-scripts/spec.md
@@ -0,0 +1,124 @@
+# dev-scripts Specification
+
+## Purpose
+Shell scripts to automate development environment setup, validation, and service orchestration for the Task Reporter system.
+
+## ADDED 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
--- a/openspec/changes/archive/2025-12-01-add-dev-scripts/tasks.md
+++ b/openspec/changes/archive/2025-12-01-add-dev-scripts/tasks.md
@@ -0,0 +1,74 @@
+# Implementation Tasks
+
+## 1. Project Structure
+- [x] 1.1 Scripts placed in project root directory
+
+## 2. Environment Check Script
+- [x] 2.1 Create `check-env.sh` with executable permissions
+- [x] 2.2 Implement Python version check (3.10+)
+- [x] 2.3 Implement Node.js and npm check
+- [x] 2.4 Implement Docker availability check
+- [x] 2.5 Implement virtual environment check (venv/)
+- [x] 2.6 Implement .env file check with template guidance
+- [x] 2.7 Implement port availability check (8000, 3000, 9000, 9001)
+- [x] 2.8 Add colored output and clear error messages
+
+## 3. Start Development Script
+- [x] 3.1 Create `start-dev.sh` with executable permissions
+- [x] 3.2 Call check-env.sh before starting services
+- [x] 3.3 Start MinIO via docker-compose (with health check wait)
+- [x] 3.4 Activate venv and start backend (uvicorn in background)
+- [x] 3.5 Wait for backend to be healthy (curl localhost:8000/health or similar)
+- [x] 3.6 Install frontend dependencies if node_modules missing
+- [x] 3.7 Start frontend dev server (npm run dev in background)
+- [x] 3.8 Display service URLs when all services are running
+- [x] 3.9 Handle Ctrl+C to trigger graceful shutdown
+
+## 4. Stop Development Script
+- [x] 4.1 Create `stop-dev.sh` with executable permissions
+- [x] 4.2 Stop frontend dev server
+- [x] 4.3 Stop backend uvicorn process
+- [x] 4.4 Stop MinIO docker container
+- [x] 4.5 Display confirmation messages
+
+## 5. Documentation
+- [x] 5.1 Add usage instructions to scripts (--help flag)
+- [x] 5.2 Update .env.example with any new required variables if needed
+
+## Summary
+
+**Completed:** All 18 tasks across 5 sections
+
+### Scripts Created (in project root)
+```
+./check-env.sh    # Environment validation
+./start-dev.sh    # Start all services
+./stop-dev.sh     # Stop all services
+```
+
+### Service Ports
+| Service  | Port | Description |
+|----------|------|-------------|
+| Backend  | 8000 | FastAPI server |
+| Frontend | 3000 | Vite dev server |
+| MinIO S3 | 9000 | Object storage API |
+| MinIO UI | 9001 | Admin console |
+
+### Usage
+
+```bash
+# Check environment prerequisites
+./check-env.sh
+
+# Start all services
+./start-dev.sh
+
+# Stop all services
+./stop-dev.sh
+
+# Start without MinIO (use external)
+./start-dev.sh --no-minio
+
+# Stop but keep MinIO running
+./stop-dev.sh --keep-minio
+```
--- a/openspec/specs/dev-scripts/spec.md
+++ b/openspec/specs/dev-scripts/spec.md
@@ -0,0 +1,123 @@
+# 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
+