feat: implement project launch script run.sh and update README

specs/003-project-launch-script/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Project Launch Script
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-12-20
+**Feature**: [Link to spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validated against the updated spec.

specs/003-project-launch-script/contracts/cli.md

@@ -0,0 +1,28 @@
+# CLI Contract: Project Launch Script
+
+## Command
+
+`./run.sh [options]`
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--help` | Show help message | N/A |
+| `--skip-install` | Skip dependency checks and installation | false |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BACKEND_PORT` | Port for the backend server | 8000 |
+| `FRONTEND_PORT` | Port for the frontend server | 5173 |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (on graceful shutdown) |
+| 1 | Missing dependencies (python/npm) |
+| 2 | Installation failure |
+| 130 | Terminated by SIGINT (Ctrl+C) |

specs/003-project-launch-script/data-model.md

@@ -0,0 +1,26 @@
+# Data Model: Project Launch Script
+
+## Entities
+
+N/A - This feature is a utility script and does not involve persistent data storage or complex data structures.
+
+## Process State
+
+The script manages the lifecycle of two primary processes:
+
+1.  **Backend Process**:
+    - Command: `python3 -m uvicorn src.app:app`
+    - Port: 8000 (default)
+    - Environment: Python Virtual Environment (`.venv`)
+
+2.  **Frontend Process**:
+    - Command: `npm run dev`
+    - Port: 5173 (default)
+    - Environment: Node.js / `node_modules`
+
+## Validation Rules
+
+- `python3` must be version 3.9 or higher.
+- `npm` must be available.
+- `backend/requirements.txt` must exist.
+- `frontend/package.json` must exist.

specs/003-project-launch-script/plan.md

@@ -0,0 +1,72 @@
+# Implementation Plan: Project Launch Script
+
+**Branch**: `003-project-launch-script` | **Date**: 2025-12-20 | **Spec**: [specs/003-project-launch-script/spec.md](specs/003-project-launch-script/spec.md)
+**Input**: Feature specification from `/specs/003-project-launch-script/spec.md`
+
+## Summary
+
+Create a root-level bash script (`run.sh`) to automate the setup and concurrent execution of the backend (FastAPI) and frontend (Svelte/Vite) development servers. The script will handle dependency checks, installation, and graceful termination of both processes.
+
+## Technical Context
+
+**Language/Version**: Python 3.9+, Node.js 18+  
+**Primary Dependencies**: `uvicorn`, `npm`, `bash`  
+**Storage**: N/A  
+**Testing**: Manual verification of service availability; `pytest` for backend logic if any.  
+**Target Platform**: Linux  
+**Project Type**: Web application (frontend + backend)  
+**Performance Goals**: Services accessible within 30 seconds.  
+**Constraints**: Must handle `SIGINT` (Ctrl+C) to kill all child processes.  
+**Scale/Scope**: Developer utility script.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Gate | Status | Rationale |
+|------|--------|-----------|
+| Python 3.9+ | PASS | Backend uses Python 3.9+ |
+| Node.js 18+ | PASS | Frontend uses Node.js 18+ |
+| Project Structure | PASS | Follows `backend/`, `frontend/` structure |
+| Executable from root | PASS | Planned as `./run.sh` |
+
+**Post-Design Re-evaluation**: Design artifacts (research, data-model, contracts) confirm compliance with all project principles. No violations found.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/003-project-launch-script/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+└── tasks.md             # Phase 2 output
+```
+
+### Source Code (repository root)
+
+```text
+run.sh                   # New launch script
+
+backend/
+├── src/
+│   └── app.py
+└── requirements.txt
+
+frontend/
+├── src/
+└── package.json
+```
+
+**Structure Decision**: Option 2: Web application. The script will reside in the root to orchestrate both directories.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| None | - | - |

specs/003-project-launch-script/quickstart.md

@@ -0,0 +1,39 @@
+# Quickstart: Project Launch Script
+
+## Prerequisites
+
+- Linux/macOS environment
+- Python 3.9+
+- Node.js 18+
+
+## Installation
+
+No installation required. The script is part of the repository.
+
+## Usage
+
+1.  Navigate to the project root:
+    ```bash
+    cd ss-tools
+    ```
+
+2.  Make the script executable (if not already):
+    ```bash
+    chmod +x run.sh
+    ```
+
+3.  Run the script:
+    ```bash
+    ./run.sh
+    ```
+
+## What it does
+
+1.  Checks for `python3` and `npm`.
+2.  Sets up a Python virtual environment in `backend/.venv` if it doesn't exist.
+3.  Installs backend dependencies from `backend/requirements.txt`.
+4.  Installs frontend dependencies if `frontend/node_modules` is missing.
+5.  Starts the backend server on port 8000.
+6.  Starts the frontend server on port 5173.
+7.  Streams logs from both services to the terminal.
+8.  Gracefully stops both services when you press `Ctrl+C`.

specs/003-project-launch-script/research.md

@@ -0,0 +1,57 @@
+# Research: Project Launch Script
+
+## Decision: Bash Script with `trap` and Background Processes
+
+### Rationale
+A bash script is the most portable and lightweight way to meet the requirement of a single command (`./run.sh`) without introducing additional process management dependencies like `pm2` or `concurrently` (unless we want to use `npm` to run everything, but the user asked for a script).
+
+### Alternatives Considered
+1.  **`concurrently` (NPM package)**:
+    - *Pros*: Easy to use, handles output well.
+    - *Cons*: Requires `npm install` before it can even run. The goal is a script that *handles* the install.
+2.  **`docker-compose`**:
+    - *Pros*: Perfect for multi-service orchestration.
+    - *Cons*: Overkill for a simple local dev environment; requires Docker to be installed and configured.
+3.  **Python script**:
+    - *Pros*: Better cross-platform support (Windows/Linux).
+    - *Cons*: Slightly more verbose for process management than bash on Linux.
+
+## Technical Findings
+
+### 1. Concurrent Execution & Graceful Shutdown
+To run processes concurrently and handle Ctrl+C:
+```bash
+#!/bin/bash
+
+# Cleanup function
+cleanup() {
+    echo "Stopping services..."
+    kill $BACKEND_PID $FRONTEND_PID
+    exit
+}
+
+# Trap SIGINT (Ctrl+C)
+trap cleanup SIGINT
+
+# Start Backend
+cd backend && python3 -m uvicorn src.app:app --reload --port 8000 &
+BACKEND_PID=$!
+
+# Start Frontend
+cd frontend && npm run dev -- --port 5173 &
+FRONTEND_PID=$!
+
+# Wait for processes
+wait
+```
+
+### 2. Dependency Checking
+- **Backend**: Check for `venv`. If missing, create it and install requirements.
+- **Frontend**: Check for `frontend/node_modules`. If missing, run `npm install`.
+
+### 3. Environment Validation
+- Check `command -v python3` and `command -v npm`.
+
+## Best Practices
+- Use colors for logs to distinguish between Backend and Frontend output.
+- Use `set -e` to exit on error during setup, but disable it or handle it carefully when starting background processes.

specs/003-project-launch-script/spec.md

@@ -0,0 +1,54 @@
+# Feature Specification: Project Launch Script
+
+**Feature Branch**: `003-project-launch-script`
+**Created**: 2025-12-20
+**Status**: Draft
+**Input**: User description: "давай создадим скрипт для запуска проекта"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Launch Project (Priority: P1)
+
+As a developer, I want to launch the entire project (backend and frontend) with a single command so that I can start working quickly without manually running multiple commands in different terminals.
+
+**Why this priority**: This is the core functionality requested. It simplifies the development workflow.
+
+**Independent Test**: Can be fully tested by running the script and verifying that both backend and frontend services are accessible.
+
+**Acceptance Scenarios**:
+
+1. **Given** the project is cloned and I am in the root directory, **When** I run the launch script, **Then** the script checks for dependencies, installs them if missing, and starts both backend and frontend servers.
+2. **Given** the servers are running, **When** I press Ctrl+C, **Then** both backend and frontend processes terminate gracefully.
+3. **Given** dependencies are missing, **When** I run the script, **Then** it installs them before starting the servers.
+
+---
+
+### Edge Cases
+
+- What happens when a port is already in use? The underlying tools (uvicorn/vite) will likely fail or complain. The script should ideally show this output.
+- What happens if `python3` or `npm` is missing? The script should fail with a clear error message.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The script MUST be executable from the project root (e.g., `./run.sh`).
+- **FR-002**: The script MUST check if `python3` and `npm` are available in the environment.
+- **FR-003**: The script MUST check for and install backend dependencies from `backend/requirements.txt` if they are missing or outdated.
+- **FR-004**: The script MUST check for and install frontend dependencies from `frontend/package.json` if `node_modules` is missing.
+- **FR-005**: The script MUST start the backend application server in development mode.
+- **FR-006**: The script MUST start the frontend application server in development mode.
+- **FR-007**: The script MUST run both backend and frontend processes concurrently.
+- **FR-008**: The script MUST handle `SIGINT` (Ctrl+C) to terminate both processes gracefully.
+
+### Key Entities *(include if feature involves data)*
+
+N/A
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Developers can start the full stack with 1 command.
+- **SC-002**: Both backend and frontend services are accessible via their configured network ports within 30 seconds of running the script (assuming dependencies are installed).
+- **SC-003**: 100% of child processes are terminated when the script is stopped.

specs/003-project-launch-script/tasks.md

@@ -0,0 +1,135 @@
+---
+
+description: "Task list for Project Launch Script implementation"
+---
+
+# Tasks: Project Launch Script
+
+**Input**: Design documents from `/specs/003-project-launch-script/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: Manual verification as per spec.md. No automated test suite requested for this utility script.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Web app**: `backend/src/`, `frontend/src/`, `run.sh` at root
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [x] T001 Create `run.sh` with basic structure and `--help` message in `run.sh`
+- [x] T002 [P] Implement environment validation for `python3` (3.9+) and `npm` in `run.sh`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T003 Implement backend dependency check and installation logic (venv + requirements.txt) in `run.sh`
+- [x] T004 Implement frontend dependency check and installation logic (node_modules) in `run.sh`
+- [x] T005 Implement `SIGINT` trap and `cleanup` function for graceful shutdown in `run.sh`
+
+**Checkpoint**: Foundation ready - user story implementation can now begin
+
+---
+
+## Phase 3: User Story 1 - Launch Project (Priority: P1) 🎯 MVP
+
+**Goal**: Launch backend and frontend concurrently with dependency management and graceful shutdown.
+
+**Independent Test**: Run `./run.sh` from root. Verify both services start, are accessible on their ports, and both stop when Ctrl+C is pressed.
+
+### Implementation for User Story 1
+
+- [x] T006 [US1] Implement backend server startup logic with `BACKEND_PORT` support in `run.sh`
+- [x] T007 [US1] Implement frontend server startup logic with `FRONTEND_PORT` support in `run.sh`
+- [x] T008 [US1] Implement concurrent execution using background processes and `wait` in `run.sh`
+- [x] T009 [US1] Implement `--skip-install` flag logic to bypass dependency checks in `run.sh`
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently.
+
+---
+
+## Phase 4: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [x] T010 [P] Add color-coded logging to distinguish between backend and frontend output in `run.sh`
+- [x] T011 [P] Update project `README.md` with `run.sh` usage instructions
+- [x] T012 Run `quickstart.md` validation for `run.sh`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+
+### Within Each User Story
+
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- T002 can run in parallel with T001 (though both edit `run.sh`, they are logically independent)
+- T010, T011 can run in parallel
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Implementation tasks for User Story 1 are mostly sequential in run.sh
+# but can be developed in separate blocks:
+Task: "Implement backend server startup logic with BACKEND_PORT support in run.sh"
+Task: "Implement frontend server startup logic with FRONTEND_PORT support in run.sh"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Each story adds value without breaking previous stories
+
+---
+
+## Notes
+
+- [P] tasks = different files or independent logic blocks
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently