scripts.md

📋 Overview

The project includes a collection of utility scripts organized by platform in the scripts/ directory. These scripts provide convenient wrappers for common development tasks.

📁 Directory Structure

scripts/
├── python/          # Core Python scripts
│   ├── setup.py     # Install dependencies and setup environment
│   ├── migrate.py   # Database migrations
│   ├── run.py       # Run the bot
│   ├── test.py      # Run tests
│   ├── lint.py      # Code linting
│   ├── format.py    # Code formatting
│   └── context_gen.py  # Generate project context
├── linux/           # Linux shell script wrappers
│   ├── setup.sh
│   ├── migrate.sh
│   ├── run.sh
│   ├── test.sh
│   ├── lint.sh
│   └── format.sh
└── windows/         # Windows PowerShell wrappers
    ├── setup.ps1
    ├── migrate.ps1
    ├── run.ps1
    ├── test.ps1
    ├── lint.ps1
    └── format.ps1

🐍 Python Scripts

All Python scripts are located in scripts/python/ and can be run directly or as modules.

Direct execution

python scripts/python/setup.py
python scripts/python/migrate.py
python scripts/python/run.py

Module execution

python -m scripts.python.setup
python -m scripts.python.migrate
python -m scripts.python.run

setup.py

Installs the package in editable mode with development dependencies and creates .env file from .env.example if it doesn't exist.

Usage:

# Linux/macOS
./scripts/linux/setup.sh

# Windows PowerShell
.\scripts\windows\setup.ps1

# Direct Python
python scripts/python/setup.py

migrate.py

Runs Alembic database migrations. Supports all Alembic commands.

Usage:

# Upgrade to latest
python scripts/python/migrate.py

# Custom Alembic command
python scripts/python/migrate.py downgrade -1
python scripts/python/migrate.py revision -m "add new table"

run.py

Applies database migrations and starts the bot.

Usage:

python scripts/python/run.py

test.py

Runs pytest with coverage. Supports pytest arguments.

Usage:

# Run all tests
python scripts/python/test.py

# Run specific test file
python scripts/python/test.py tests/test_invoice_service.py

# Run with marker
python scripts/python/test.py -m "not storage_db"

lint.py

Runs code quality checks: ruff check and mypy type checking.

Usage:

python scripts/python/lint.py

format.py

Formats code using ruff formatter.

Usage:

python scripts/python/format.py

context_gen.py

Generates a full project context file (full_project_context.txt) containing all project files for AI context.

Usage:

python scripts/python/context_gen.py

🐧 Linux Scripts

Linux shell script wrappers are located in scripts/linux/. They provide convenient shortcuts to Python scripts.

Make scripts executable:

chmod +x scripts/linux/*.sh

Usage:

./scripts/linux/setup.sh
./scripts/linux/migrate.sh
./scripts/linux/run.sh
./scripts/linux/test.sh
./scripts/linux/lint.sh
./scripts/linux/format.sh

All scripts support passing arguments to the underlying Python scripts:

./scripts/linux/test.sh -m "not storage_db"
./scripts/linux/migrate.sh downgrade -1

🪟 Windows Scripts

Windows PowerShell script wrappers are located in scripts/windows/.

Usage:

.\scripts\windows\setup.ps1
.\scripts\windows\migrate.ps1
.\scripts\windows\run.ps1
.\scripts\windows\test.ps1
.\scripts\windows\lint.ps1
.\scripts\windows\format.ps1

Note: If you encounter execution policy restrictions, run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

All scripts support passing arguments:

.\scripts\windows\test.ps1 -m "not storage_db"
.\scripts\windows\migrate.ps1 downgrade -1

🔄 Typical Workflow

Initial Setup

# Linux/macOS
./scripts/linux/setup.sh

# Windows
.\scripts\windows\setup.ps1

Development Cycle

# Format code
./scripts/linux/format.sh    # or .\scripts\windows\format.ps1

# Lint code
./scripts/linux/lint.sh      # or .\scripts\windows\lint.ps1

# Run tests
./scripts/linux/test.sh      # or .\scripts\windows\test.ps1

# Run migrations
./scripts/linux/migrate.sh   # or .\scripts\windows\migrate.ps1

# Start bot
./scripts/linux/run.sh       # or .\scripts\windows\run.ps1

📝 Notes

• All scripts automatically detect the project root directory
• Scripts work from any location within the project
• Python scripts can be run directly or as modules
• Shell/PowerShell scripts are thin wrappers that pass arguments through
• All scripts use relative paths and are portable

---