egg/Task_Reporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
Task_Reporter/openspec/specs/dev-scripts/spec.md
egg 77091eefb5 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

4.2 KiB
Raw Permalink Blame History

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