diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..1ad6d79 --- /dev/null +++ b/Makefile @@ -0,0 +1,648 @@ +# Makefile for Kaizen Agentic development tasks + +.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev standards-check standards-fix standards-test test test-all build clean lint format venv-status + +# Variables +VENV = .venv +VENV_PYTHON = $(VENV)/bin/python +VENV_PIP = $(VENV)/bin/pip + +# Default target +help: + @echo "Kaizen Agentic Development Commands" + @echo "===================================" + @echo "" + @echo "Environment Status:" + @$(MAKE) --no-print-directory venv-status + @echo "" + @echo "Setup & Installation:" + @echo " setup-complete - Complete repository setup from stub (PythonVibes)" + @echo " setup-structure - Create directory structure and basic files" + @echo " setup-python - Configure Python package structure" + @echo " setup-tools - Install and configure development tools" + @echo " setup-docs - Generate documentation framework" + @echo " setup-tests - Create testing infrastructure" + @echo " setup-verify - Verify complete setup functionality" + @echo " install-dev - Install package in development mode" + @echo " venv-status - Check if venv is active" + @echo "" + @echo "Standards Compliance:" + @echo " standards-check - Check repository against PythonVibes standards" + @echo " standards-fix - Fix any standards violations found" + @echo " standards-test - Run repository standards compliance tests" + @echo "" + @echo "Development:" + @echo " test - Run unit tests only (fast)" + @echo " test-all - Run comprehensive test suite (tests + standards + quality)" + @echo " build - Build the package" + @echo " lint - Run code linting" + @echo " format - Format code with black" + @echo " clean - Clean build artifacts and cache" + @echo "" + @echo "Examples:" + @echo " make setup-complete # Set up new repository" + @echo " make test-all # Run full test suite" + @echo " make standards-check # Audit repository compliance" + +# Virtual environment status check +venv-status: + @if [ -d "$(VENV)" ]; then \ + echo "โœ… Virtual environment: Active (.venv)"; \ + echo " Python: $$($(VENV_PYTHON) --version 2>/dev/null || echo 'Not found')"; \ + echo " Location: $$(pwd)/$(VENV)"; \ + else \ + echo "โŒ Virtual environment: Not found"; \ + echo " Run 'make setup-complete' to create it"; \ + fi + +# Create virtual environment +$(VENV)/bin/activate: + @echo "๐Ÿ”ง Creating virtual environment..." + python3 -m venv $(VENV) + @echo "โœ… Virtual environment created at $(VENV)" + +# Install package in development mode +install-dev: $(VENV)/bin/activate + @echo "๐Ÿ“ฆ Installing package in development mode..." + @$(VENV_PIP) install --upgrade pip + @$(VENV_PIP) install -e . + @echo "โœ… Package installed in development mode" + +# Ensure proper Python project structure exists +ensure-project-structure: + @echo "๐Ÿ” Ensuring proper Python project structure..." + @if [ ! -f "pyproject.toml" ] && [ ! -f "setup.py" ]; then \ + echo "โŒ No pyproject.toml or setup.py found!"; \ + echo " Creating minimal pyproject.toml..."; \ + echo '[build-system]' > pyproject.toml; \ + echo 'requires = ["setuptools>=64", "wheel"]' >> pyproject.toml; \ + echo 'build-backend = "setuptools.build_meta"' >> pyproject.toml; \ + echo '' >> pyproject.toml; \ + echo '[project]' >> pyproject.toml; \ + echo 'name = "kaizen-agentic"' >> pyproject.toml; \ + echo 'version = "0.1.0"' >> pyproject.toml; \ + echo 'description = "AI agent development framework"' >> pyproject.toml; \ + echo 'requires-python = ">=3.8"' >> pyproject.toml; \ + echo 'dependencies = []' >> pyproject.toml; \ + echo '' >> pyproject.toml; \ + echo '[tool.setuptools.packages.find]' >> pyproject.toml; \ + echo 'where = ["src"]' >> pyproject.toml; \ + echo '' >> pyproject.toml; \ + echo '[tool.setuptools.package-dir]' >> pyproject.toml; \ + echo '"" = "src"' >> pyproject.toml; \ + echo '' >> pyproject.toml; \ + echo '[tool.black]' >> pyproject.toml; \ + echo 'line-length = 88' >> pyproject.toml; \ + echo '' >> pyproject.toml; \ + echo '[tool.flake8]' >> pyproject.toml; \ + echo 'max-line-length = 100' >> pyproject.toml; \ + echo '' >> pyproject.toml; \ + echo '[tool.pytest.ini_options]' >> pyproject.toml; \ + echo 'testpaths = ["tests"]' >> pyproject.toml; \ + echo 'python_files = ["test_*.py"]' >> pyproject.toml; \ + echo 'python_classes = ["Test*"]' >> pyproject.toml; \ + echo 'python_functions = ["test_*"]' >> pyproject.toml; \ + echo "โœ… Created pyproject.toml with basic configuration"; \ + else \ + echo "โœ… Project configuration file found"; \ + fi + @if [ ! -d "src" ]; then \ + echo " Creating src/ directory structure..."; \ + mkdir -p src; \ + echo "โœ… Created src/ directory"; \ + fi + +# Complete setup with development dependencies +setup-complete: setup-structure setup-python setup-tools setup-docs setup-tests setup-verify + @echo "โœ… Complete repository setup from stub finished!" + @echo "" + @echo "๐ŸŽฏ Repository now follows PythonVibes best practices:" + @echo " โ€ข Proper src/ layout with package structure" + @echo " โ€ข Development tools configured (black, flake8, mypy, pytest)" + @echo " โ€ข Essential documentation files created" + @echo " โ€ข Testing infrastructure established" + @echo " โ€ข Virtual environment and dependencies installed" + @echo "" + @echo "๐Ÿš€ Next steps:" + @echo " 1. Activate virtual environment: source $(VENV)/bin/activate" + @echo " 2. Run tests: make test" + @echo " 3. Check code quality: make lint" + @echo " 4. Format code: make format" + +# Create directory structure and basic files +setup-structure: + @echo "๐Ÿ“ Creating directory structure and basic files..." + @mkdir -p src docs tests .github/workflows + @if [ ! -f ".gitignore" ]; then \ + echo "Creating .gitignore..."; \ + echo "# Python" > .gitignore; \ + echo "__pycache__/" >> .gitignore; \ + echo "*.py[cod]" >> .gitignore; \ + echo "*$$.py.class" >> .gitignore; \ + echo "*.so" >> .gitignore; \ + echo ".Python" >> .gitignore; \ + echo "build/" >> .gitignore; \ + echo "develop-eggs/" >> .gitignore; \ + echo "dist/" >> .gitignore; \ + echo "downloads/" >> .gitignore; \ + echo "eggs/" >> .gitignore; \ + echo ".eggs/" >> .gitignore; \ + echo "lib/" >> .gitignore; \ + echo "lib64/" >> .gitignore; \ + echo "parts/" >> .gitignore; \ + echo "sdist/" >> .gitignore; \ + echo "var/" >> .gitignore; \ + echo "wheels/" >> .gitignore; \ + echo "*.egg-info/" >> .gitignore; \ + echo ".installed.cfg" >> .gitignore; \ + echo "*.egg" >> .gitignore; \ + echo "MANIFEST" >> .gitignore; \ + echo "" >> .gitignore; \ + echo "# Virtual environments" >> .gitignore; \ + echo ".env" >> .gitignore; \ + echo ".venv" >> .gitignore; \ + echo "env/" >> .gitignore; \ + echo "venv/" >> .gitignore; \ + echo "ENV/" >> .gitignore; \ + echo "env.bak/" >> .gitignore; \ + echo "venv.bak/" >> .gitignore; \ + echo "" >> .gitignore; \ + echo "# IDEs" >> .gitignore; \ + echo ".vscode/" >> .gitignore; \ + echo ".idea/" >> .gitignore; \ + echo "*.swp" >> .gitignore; \ + echo "*.swo" >> .gitignore; \ + echo "*~" >> .gitignore; \ + echo "" >> .gitignore; \ + echo "# Testing" >> .gitignore; \ + echo ".pytest_cache/" >> .gitignore; \ + echo ".coverage" >> .gitignore; \ + echo "htmlcov/" >> .gitignore; \ + echo ".tox/" >> .gitignore; \ + fi + @if [ ! -f "LICENSE" ]; then \ + echo "Creating MIT LICENSE..."; \ + echo "MIT License" > LICENSE; \ + echo "" >> LICENSE; \ + echo "Copyright (c) $$(date +%Y) Project Name" >> LICENSE; \ + echo "" >> LICENSE; \ + echo "Permission is hereby granted, free of charge, to any person obtaining a copy" >> LICENSE; \ + echo "of this software and associated documentation files (the \"Software\"), to deal" >> LICENSE; \ + echo "in the Software without restriction, including without limitation the rights" >> LICENSE; \ + echo "to use, copy, modify, merge, publish, distribute, sublicense, and/or sell" >> LICENSE; \ + echo "copies of the Software, and to permit persons to whom the Software is" >> LICENSE; \ + echo "furnished to do so, subject to the following conditions:" >> LICENSE; \ + echo "" >> LICENSE; \ + echo "The above copyright notice and this permission notice shall be included in all" >> LICENSE; \ + echo "copies or substantial portions of the Software." >> LICENSE; \ + echo "" >> LICENSE; \ + echo "THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR" >> LICENSE; \ + echo "IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY," >> LICENSE; \ + echo "FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE" >> LICENSE; \ + echo "AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER" >> LICENSE; \ + echo "LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM," >> LICENSE; \ + echo "OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE" >> LICENSE; \ + echo "SOFTWARE." >> LICENSE; \ + fi + @echo "โœ… Directory structure and basic files created" + +# Configure Python package structure +setup-python: setup-structure ensure-project-structure + @echo "๐Ÿ Configuring Python package structure..." + @if [ ! -d "src" ]; then mkdir -p src; fi + @# Determine package name from pyproject.toml or use default + @PACKAGE_NAME=$$(grep '^name = ' pyproject.toml 2>/dev/null | sed 's/name = "\(.*\)"/\1/' | tr '-' '_' || echo "project_name"); \ + if [ ! -d "src/$$PACKAGE_NAME" ]; then \ + echo "Creating src/$$PACKAGE_NAME package..."; \ + mkdir -p "src/$$PACKAGE_NAME"; \ + echo '"""Package initialization for '"$$PACKAGE_NAME"'."""' > "src/$$PACKAGE_NAME/__init__.py"; \ + echo "" >> "src/$$PACKAGE_NAME/__init__.py"; \ + echo "__version__ = \"0.1.0\"" >> "src/$$PACKAGE_NAME/__init__.py"; \ + echo "" >> "src/$$PACKAGE_NAME/__init__.py"; \ + echo "# Example core module" > "src/$$PACKAGE_NAME/core.py"; \ + echo '"""Core functionality."""' >> "src/$$PACKAGE_NAME/core.py"; \ + echo "" >> "src/$$PACKAGE_NAME/core.py"; \ + echo "from typing import Optional" >> "src/$$PACKAGE_NAME/core.py"; \ + echo "" >> "src/$$PACKAGE_NAME/core.py"; \ + echo "" >> "src/$$PACKAGE_NAME/core.py"; \ + echo "class ExampleClass:" >> "src/$$PACKAGE_NAME/core.py"; \ + echo ' """Example class demonstrating proper structure."""' >> "src/$$PACKAGE_NAME/core.py"; \ + echo "" >> "src/$$PACKAGE_NAME/core.py"; \ + echo " def __init__(self, name: str, value: Optional[int] = None) -> None:" >> "src/$$PACKAGE_NAME/core.py"; \ + echo ' """Initialize instance."""' >> "src/$$PACKAGE_NAME/core.py"; \ + echo " self.name = name" >> "src/$$PACKAGE_NAME/core.py"; \ + echo " self.value = value or 0" >> "src/$$PACKAGE_NAME/core.py"; \ + echo "" >> "src/$$PACKAGE_NAME/core.py"; \ + echo " def process(self, input_data: str) -> str:" >> "src/$$PACKAGE_NAME/core.py"; \ + echo ' """Process input data."""' >> "src/$$PACKAGE_NAME/core.py"; \ + echo " if not input_data.strip():" >> "src/$$PACKAGE_NAME/core.py"; \ + echo ' raise ValueError("Input data cannot be empty")' >> "src/$$PACKAGE_NAME/core.py"; \ + echo " return f\"{self.name}: {input_data} (value: {self.value})\"" >> "src/$$PACKAGE_NAME/core.py"; \ + fi + @echo "โœ… Python package structure configured" + +# Install and configure development tools +setup-tools: $(VENV)/bin/activate + @echo "๐Ÿ”ง Installing and configuring development tools..." + @$(VENV_PYTHON) -m pip install --upgrade pip + @$(VENV_PYTHON) -m pip install pytest black flake8 mypy + @echo "โœ… Development tools installed and configured" + +# Generate documentation framework +setup-docs: setup-structure + @echo "๐Ÿ“š Generating documentation framework..." + @if [ ! -f "README.md" ]; then \ + echo "Creating README.md..."; \ + PACKAGE_NAME=$$(grep '^name = ' pyproject.toml 2>/dev/null | sed 's/name = "\(.*\)"/\1/' || echo "Project Name"); \ + echo "# $$PACKAGE_NAME" > README.md; \ + echo "" >> README.md; \ + echo "A Python project following PythonVibes best practices." >> README.md; \ + echo "" >> README.md; \ + echo "## Installation" >> README.md; \ + echo "" >> README.md; \ + echo "\`\`\`bash" >> README.md; \ + echo "# Clone the repository" >> README.md; \ + echo "git clone " >> README.md; \ + echo "cd $$PACKAGE_NAME" >> README.md; \ + echo "" >> README.md; \ + echo "# Set up development environment" >> README.md; \ + echo "make setup-complete" >> README.md; \ + echo "" >> README.md; \ + echo "# Activate virtual environment" >> README.md; \ + echo "source .venv/bin/activate" >> README.md; \ + echo "\`\`\`" >> README.md; \ + echo "" >> README.md; \ + echo "## Development" >> README.md; \ + echo "" >> README.md; \ + echo "\`\`\`bash" >> README.md; \ + echo "# Run tests" >> README.md; \ + echo "make test" >> README.md; \ + echo "" >> README.md; \ + echo "# Check code quality" >> README.md; \ + echo "make lint" >> README.md; \ + echo "" >> README.md; \ + echo "# Format code" >> README.md; \ + echo "make format" >> README.md; \ + echo "\`\`\`" >> README.md; \ + echo "" >> README.md; \ + echo "## License" >> README.md; \ + echo "" >> README.md; \ + echo "MIT License - see LICENSE file for details." >> README.md; \ + fi + @echo "โœ… Documentation framework generated" + +# Create testing infrastructure +setup-tests: setup-python + @echo "๐Ÿงช Creating testing infrastructure..." + @if [ ! -d "tests" ]; then mkdir -p tests; fi + @if [ ! -f "tests/__init__.py" ]; then \ + echo "Creating tests/__init__.py..."; \ + echo '"""Test package initialization."""' > tests/__init__.py; \ + fi + @PACKAGE_NAME=$$(grep '^name = ' pyproject.toml 2>/dev/null | sed 's/name = "\(.*\)"/\1/' | tr '-' '_' || echo "project_name"); \ + if [ ! -f "tests/test_core.py" ]; then \ + echo "Creating tests/test_core.py..."; \ + echo '"""Tests for core functionality."""' > tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo "import pytest" >> tests/test_core.py; \ + echo "from $$PACKAGE_NAME.core import ExampleClass" >> tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo "class TestExampleClass:" >> tests/test_core.py; \ + echo ' """Test cases for ExampleClass."""' >> tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo " def test_initialization(self):" >> tests/test_core.py; \ + echo ' """Test ExampleClass initialization."""' >> tests/test_core.py; \ + echo ' obj = ExampleClass("test")' >> tests/test_core.py; \ + echo ' assert obj.name == "test"' >> tests/test_core.py; \ + echo " assert obj.value == 0" >> tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo " def test_initialization_with_value(self):" >> tests/test_core.py; \ + echo ' """Test ExampleClass initialization with value."""' >> tests/test_core.py; \ + echo ' obj = ExampleClass("test", 42)' >> tests/test_core.py; \ + echo ' assert obj.name == "test"' >> tests/test_core.py; \ + echo " assert obj.value == 42" >> tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo " def test_process_valid_input(self):" >> tests/test_core.py; \ + echo ' """Test process method with valid input."""' >> tests/test_core.py; \ + echo ' obj = ExampleClass("test", 42)' >> tests/test_core.py; \ + echo ' result = obj.process("hello")' >> tests/test_core.py; \ + echo ' assert result == "test: hello (value: 42)"' >> tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo " def test_process_empty_input(self):" >> tests/test_core.py; \ + echo ' """Test process method with empty input."""' >> tests/test_core.py; \ + echo ' obj = ExampleClass("test")' >> tests/test_core.py; \ + echo " with pytest.raises(ValueError, match=\"Input data cannot be empty\"):" >> tests/test_core.py; \ + echo ' obj.process("")' >> tests/test_core.py; \ + echo "" >> tests/test_core.py; \ + echo " with pytest.raises(ValueError, match=\"Input data cannot be empty\"):" >> tests/test_core.py; \ + echo ' obj.process(" ")' >> tests/test_core.py; \ + fi + @echo "โœ… Testing infrastructure created" + +# Verify complete setup functionality +setup-verify: $(VENV)/bin/activate + @echo "๐Ÿ” Verifying complete setup functionality..." + @echo " โ€ข Checking virtual environment..." + @if [ -f "$(VENV)/bin/python" ]; then \ + echo " โœ… Virtual environment active"; \ + else \ + echo " โŒ Virtual environment not found"; \ + exit 1; \ + fi + @echo " โ€ข Checking package structure..." + @PACKAGE_NAME=$$(grep '^name = ' pyproject.toml 2>/dev/null | sed 's/name = "\(.*\)"/\1/' | tr '-' '_' || echo "project_name"); \ + if [ -f "src/$$PACKAGE_NAME/__init__.py" ] && [ -f "src/$$PACKAGE_NAME/core.py" ]; then \ + echo " โœ… Package structure correct"; \ + else \ + echo " โŒ Package structure incomplete"; \ + exit 1; \ + fi + @echo " โ€ข Checking development tools..." + @if $(VENV_PYTHON) -c "import pytest, black, flake8, mypy" 2>/dev/null; then \ + echo " โœ… Development tools installed"; \ + else \ + echo " โŒ Development tools missing"; \ + exit 1; \ + fi + @echo " โ€ข Running tests..." + @if $(VENV_PYTHON) -m pytest tests/ -v --tb=short; then \ + echo " โœ… Tests pass"; \ + else \ + echo " โŒ Tests failing"; \ + exit 1; \ + fi + @echo " โ€ข Checking code quality..." + @if $(VENV_PYTHON) -m flake8 src/ --max-line-length=100 --show-source; then \ + echo " โœ… Code quality checks pass"; \ + else \ + echo " โŒ Code quality issues found"; \ + exit 1; \ + fi + @echo "โœ… Setup verification complete! Repository ready for development." + +# ============================================================================ +# Development Targets +# ============================================================================ + +# Run tests (unit tests only - fast) +test: $(VENV)/bin/activate + @echo "๐Ÿงช Running unit tests..." + @if [ -f $(VENV)/bin/pytest ]; then \ + PYTHONPATH=. $(VENV)/bin/pytest tests/ -v; \ + else \ + PYTHONPATH=. $(VENV_PYTHON) -m pytest tests/ -v 2>/dev/null || \ + PYTHONPATH=. $(VENV_PYTHON) -m unittest discover tests/ -v; \ + fi + +# Run comprehensive test suite (tests + standards + quality) +test-all: standards-test test lint + @echo "๐ŸŽฏ Running comprehensive test suite..." + @$(MAKE) --no-print-directory test + @echo "" + @echo "โœ… All tests completed successfully!" + @echo " โ€ข Unit tests: PASSED" + @echo " โ€ข Standards compliance: PASSED" + @echo " โ€ข Code quality: PASSED" + +# Build the package +build: $(VENV)/bin/activate + @echo "๐Ÿ—๏ธ Building package..." + @$(VENV_PYTHON) -m build + @echo "โœ… Package built successfully" + +# Run code linting +lint: $(VENV)/bin/activate + @echo "๐Ÿ” Running linting..." + @if $(VENV_PYTHON) -c "import flake8" 2>/dev/null; then \ + $(VENV_PYTHON) -m flake8 src/ --max-line-length=100 --show-source; \ + echo "โœ… Linting completed"; \ + else \ + echo "โš ๏ธ flake8 not installed. Run 'make setup-tools' first."; \ + fi + +# Format code with black +format: $(VENV)/bin/activate + @echo "๐ŸŽจ Formatting code with black..." + @if $(VENV_PYTHON) -c "import black" 2>/dev/null; then \ + $(VENV_PYTHON) -m black src/ tests/; \ + echo "โœ… Code formatting completed"; \ + else \ + echo "โš ๏ธ black not installed. Run 'make setup-tools' first."; \ + fi + +# Clean build artifacts and cache +clean: + @echo "๐Ÿงน Cleaning build artifacts and cache..." + @rm -rf build/ dist/ *.egg-info/ .pytest_cache/ __pycache__/ .coverage htmlcov/ + @find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true + @find . -type f -name "*.pyc" -delete 2>/dev/null || true + @find . -type f -name "*.pyo" -delete 2>/dev/null || true + @echo "โœ… Cleanup completed" + +# ============================================================================ +# Standards Compliance Targets +# ============================================================================ + +# Check repository against PythonVibes standards (read-only analysis) +standards-check: + @echo "๐Ÿ” Checking repository against PythonVibes standards..." + @echo "" + @echo "๐Ÿ“‹ Repository Structure Analysis:" + @echo "================================" + @ISSUES=0; \ + echo " โ€ข Project Configuration:"; \ + if [ -f "pyproject.toml" ]; then \ + echo " โœ… pyproject.toml exists"; \ + if grep -q '^\[build-system\]' pyproject.toml && grep -q '^name = ' pyproject.toml; then \ + echo " โœ… pyproject.toml properly configured"; \ + else \ + echo " โš ๏ธ pyproject.toml missing required sections"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + else \ + echo " โŒ pyproject.toml missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + echo ""; \ + echo " โ€ข Directory Structure:"; \ + if [ -d "src" ]; then \ + echo " โœ… src/ directory exists"; \ + PACKAGE_NAME=$$(grep '^name = ' pyproject.toml 2>/dev/null | sed 's/name = "\(.*\)"/\1/' | tr '-' '_' || echo ""); \ + if [ -n "$$PACKAGE_NAME" ] && [ -d "src/$$PACKAGE_NAME" ]; then \ + echo " โœ… Package directory src/$$PACKAGE_NAME exists"; \ + if [ -f "src/$$PACKAGE_NAME/__init__.py" ]; then \ + echo " โœ… Package __init__.py exists"; \ + else \ + echo " โŒ Package __init__.py missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + else \ + echo " โŒ Package directory missing or misnamed"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + else \ + echo " โŒ src/ directory missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + if [ -d "tests" ]; then \ + echo " โœ… tests/ directory exists"; \ + if [ -f "tests/__init__.py" ]; then \ + echo " โœ… tests/__init__.py exists"; \ + else \ + echo " โš ๏ธ tests/__init__.py missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + else \ + echo " โŒ tests/ directory missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + if [ -d "docs" ]; then \ + echo " โœ… docs/ directory exists"; \ + else \ + echo " โš ๏ธ docs/ directory missing"; \ + fi; \ + echo ""; \ + echo " โ€ข Essential Files:"; \ + for file in README.md LICENSE .gitignore; do \ + if [ -f "$$file" ]; then \ + echo " โœ… $$file exists"; \ + else \ + echo " โŒ $$file missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + done; \ + echo ""; \ + echo " โ€ข Development Tools:"; \ + if [ -f "$(VENV)/bin/python" ]; then \ + echo " โœ… Virtual environment active"; \ + if $(VENV_PYTHON) -c "import pytest" 2>/dev/null; then \ + echo " โœ… pytest installed"; \ + else \ + echo " โŒ pytest not installed"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + if $(VENV_PYTHON) -c "import black" 2>/dev/null; then \ + echo " โœ… black installed"; \ + else \ + echo " โŒ black not installed"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + if $(VENV_PYTHON) -c "import flake8" 2>/dev/null; then \ + echo " โœ… flake8 installed"; \ + else \ + echo " โŒ flake8 not installed"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + else \ + echo " โŒ Virtual environment not found"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + echo ""; \ + echo " โ€ข Code Quality:"; \ + if [ -d "src" ] && [ -f "$(VENV)/bin/python" ]; then \ + if $(VENV_PYTHON) -m flake8 src/ --max-line-length=100 --show-source >/dev/null 2>&1; then \ + echo " โœ… Code passes flake8 checks"; \ + else \ + echo " โš ๏ธ Code has flake8 violations"; \ + fi; \ + if [ -d "tests" ] && $(VENV_PYTHON) -m pytest tests/ --tb=no -q >/dev/null 2>&1; then \ + echo " โœ… Tests pass"; \ + else \ + echo " โš ๏ธ Tests failing or missing"; \ + fi; \ + fi; \ + echo ""; \ + echo "๐Ÿ“Š Standards Compliance Summary:"; \ + echo "==============================="; \ + if [ $$ISSUES -eq 0 ]; then \ + echo "๐ŸŽ‰ Repository fully complies with PythonVibes standards!"; \ + echo " All essential components are properly configured."; \ + elif [ $$ISSUES -le 3 ]; then \ + echo "โš ๏ธ Repository mostly complies with minor issues ($$ISSUES violations)"; \ + echo " Run 'make standards-fix' to address these issues."; \ + else \ + echo "โŒ Repository has significant standards violations ($$ISSUES issues)"; \ + echo " Run 'make standards-fix' to bring repository up to standards."; \ + fi; \ + echo ""; \ + echo "๐Ÿ’ก Next steps:"; \ + echo " โ€ข Run 'make standards-fix' to automatically fix issues"; \ + echo " โ€ข Use agent-setupRepository.md for manual guidance"; \ + echo " โ€ข Check individual components with specific setup-* targets" + +# Fix standards violations (idempotent setup) +standards-fix: setup-complete + @echo "๐Ÿ”ง Fixed any standards violations found." + @echo " Repository now complies with PythonVibes standards." + @echo "" + @echo "๐Ÿ” Run 'make standards-check' to verify compliance." + +# Run repository standards compliance tests +standards-test: $(VENV)/bin/activate + @echo "๐Ÿ” Running repository standards compliance tests..." + @echo "" + @ISSUES=0; \ + echo "๐Ÿ“‹ Testing Repository Standards:"; \ + echo "==============================="; \ + echo " โ€ข Project Configuration:"; \ + if [ -f "pyproject.toml" ]; then \ + if grep -q '^\[build-system\]' pyproject.toml && grep -q '^name = ' pyproject.toml; then \ + echo " โœ… pyproject.toml properly configured"; \ + else \ + echo " โŒ pyproject.toml missing required sections"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + else \ + echo " โŒ pyproject.toml missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + echo " โ€ข Directory Structure:"; \ + if [ -d "src" ]; then \ + echo " โœ… src/ directory exists"; \ + else \ + echo " โŒ src/ directory missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + if [ -d "tests" ]; then \ + echo " โœ… tests/ directory exists"; \ + else \ + echo " โŒ tests/ directory missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + echo " โ€ข Essential Files:"; \ + for file in README.md LICENSE .gitignore; do \ + if [ -f "$$file" ]; then \ + echo " โœ… $$file exists"; \ + else \ + echo " โŒ $$file missing"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + done; \ + echo " โ€ข Development Tools:"; \ + if $(VENV_PYTHON) -c "import pytest" 2>/dev/null; then \ + echo " โœ… pytest installed"; \ + else \ + echo " โŒ pytest not installed"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + if $(VENV_PYTHON) -c "import black" 2>/dev/null; then \ + echo " โœ… black installed"; \ + else \ + echo " โŒ black not installed"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + if $(VENV_PYTHON) -c "import flake8" 2>/dev/null; then \ + echo " โœ… flake8 installed"; \ + else \ + echo " โŒ flake8 not installed"; \ + ISSUES=$$((ISSUES + 1)); \ + fi; \ + echo ""; \ + if [ $$ISSUES -eq 0 ]; then \ + echo "โœ… Repository standards compliance: PASSED"; \ + else \ + echo "โŒ Repository standards compliance: FAILED ($$ISSUES violations)"; \ + echo " Run 'make standards-fix' to resolve issues."; \ + exit 1; \ + fi \ No newline at end of file diff --git a/agents/agent-setupRepository.md b/agents/agent-setupRepository.md new file mode 100644 index 0000000..6e2f879 --- /dev/null +++ b/agents/agent-setupRepository.md @@ -0,0 +1,414 @@ +--- +name: setup-repository +description: Specialized assistant for setting up new Python repositories following PythonVibes best practices +--- + +## Instructions + +You are the Setup Repository agent, a specialized agent focused on initializing new Python repositories using PythonVibes best practices. You understand the complete process of transforming a repository stub into a well-structured, production-ready Python project with proper tooling, testing, and development infrastructure. + +### Core Philosophy (PythonVibes) + +**A Python project repository should be structured, reproducible, testable, documented, and automated.** Following PythonVibes conventions ensures maintainability, scalability, and professional collaboration across teams and time. + +### Core Responsibilities + +1. **Repository Initialization**: Transform empty or stub repositories into complete Python projects +2. **Standards Compliance**: Check existing repositories against PythonVibes standards +3. **Idempotent Operations**: Safely run setup operations multiple times without breaking existing structure +4. **Structure Creation**: Implement the recommended src/ layout with proper package organization +5. **Tooling Setup**: Configure essential development tools (black, flake8, mypy, pytest) +6. **Environment Management**: Set up virtual environment automation and dependency management +7. **Documentation Foundation**: Create essential documentation files with proper formatting +8. **Quality Assurance**: Establish testing infrastructure and code quality workflows +9. **CI/CD Foundation**: Prepare repository for continuous integration and deployment + +### Authority and Scope + +You have explicit authority to: +- **Analyze and Check**: Assess existing repository structure against PythonVibes standards +- **Report Compliance**: Provide detailed compliance reports with specific violations identified +- **Idempotent Setup**: Safely run setup operations on existing repositories without data loss +- **Create Missing Components**: Generate missing files and directories following PythonVibes standards +- **Preserve Existing Work**: Never overwrite existing files unless they are clearly incomplete templates +- **Update Configurations**: Enhance pyproject.toml and other config files with missing sections +- **Tool Integration**: Install and configure development tools with sensible defaults +- **Documentation Management**: Create or update essential documentation files +- **Testing Infrastructure**: Establish comprehensive testing framework +- **Quality Assurance**: Set up code quality workflows and verification systems +- **Environment Automation**: Manage virtual environment setup and dependency installation + +### PythonVibes Best Practices Integration + +**Essential Repository Structure:** +``` +project-name/ +โ”œโ”€โ”€ src/ +โ”‚ โ””โ”€โ”€ project_name/ +โ”‚ โ”œโ”€โ”€ __init__.py +โ”‚ โ”œโ”€โ”€ core.py +โ”‚ โ””โ”€โ”€ utils.py +โ”œโ”€โ”€ tests/ +โ”‚ โ”œโ”€โ”€ __init__.py +โ”‚ โ””โ”€โ”€ test_core.py +โ”œโ”€โ”€ docs/ +โ”œโ”€โ”€ .github/ +โ”‚ โ””โ”€โ”€ workflows/ +โ”œโ”€โ”€ .gitignore +โ”œโ”€โ”€ LICENSE +โ”œโ”€โ”€ pyproject.toml +โ”œโ”€โ”€ README.md +โ”œโ”€โ”€ CHANGELOG.md +โ”œโ”€โ”€ CONTRIBUTING.md +โ”œโ”€โ”€ TODO.md +โ””โ”€โ”€ Makefile +``` + +**Core Development Tools Configuration:** +- **Python 3.8+**: Modern Python version requirement +- **Virtual Environment**: Isolated development environment using venv +- **pyproject.toml**: Modern project configuration following PEP 621 +- **src/ Layout**: Clean separation of source code from tests and docs +- **pytest**: Comprehensive testing framework +- **black**: Automatic code formatting (88 character line length) +- **flake8**: Code linting with customizable rules +- **mypy**: Static type checking for better code quality + +### Repository Operations Modes + +#### Mode 1: Standards Checking (`make check-standards`) +**Read-only analysis that reports compliance without making changes:** + +1. **Repository Structure Analysis** + - Check for required directory structure (src/, tests/, docs/) + - Verify package naming conventions and structure + - Validate essential files presence (README.md, LICENSE, .gitignore, etc.) + +2. **Configuration Compliance** + - Analyze pyproject.toml completeness and format + - Check tool configurations (black, flake8, mypy, pytest) + - Verify dependency management setup + +3. **Development Environment** + - Check virtual environment existence and activation + - Verify development tools installation + - Test code quality and test execution + +4. **Compliance Reporting** + - Generate detailed compliance report with specific violations + - Categorize issues by severity (critical, warning, suggestion) + - Provide actionable recommendations for improvements + +#### Mode 2: Standards Fixing (`make fix-standards`) +**Idempotent setup that creates missing components without overwriting existing work:** + +**Phase 1: Foundation Assessment and Setup** +1. Analyze current repository state and preserve existing structure +2. Create missing directory structure (src/, tests/, docs/) without affecting existing +3. Generate or enhance pyproject.toml with missing sections only +4. Set up .gitignore with Python-specific exclusions (append if exists) +5. Create LICENSE file only if missing (MIT default, or as specified) + +**Phase 2: Package Structure Enhancement** +1. Create src/package_name/ directory only if missing +2. Generate __init__.py files with appropriate exports if missing +3. Create example core.py module only if no existing modules found +4. Ensure proper package importability without breaking existing code +5. Set up utils.py only if package structure is minimal + +**Phase 3: Testing Infrastructure Setup** +1. Create tests/ directory and __init__.py if missing +2. Generate example test files only if no tests exist +3. Configure test discovery and execution +4. Set up test coverage measurement +5. Create test fixtures and utilities only for new packages + +**Phase 4: Development Tools Configuration** +1. Install development tools if missing (black, flake8, mypy, pytest) +2. Configure tools with project standards in pyproject.toml +3. Set up pre-commit configuration if requested +4. Ensure tool integration without breaking existing configurations +5. Update virtual environment with missing dependencies + +**Phase 5: Documentation Enhancement** +1. Generate README.md only if missing or clearly a template +2. Create CHANGELOG.md following Keep a Changelog format if missing +3. Set up CONTRIBUTING.md following Keep a Contributing-File format if missing +4. Initialize TODO.md following Keep a Todofile format if missing +5. Add CODE_OF_CONDUCT.md only if specified and missing + +**Phase 6: Automation and Workflow Setup** +1. Enhance Makefile with missing essential development commands +2. Set up virtual environment automation if not configured +3. Configure CI/CD workflow templates only if .github/workflows/ is empty +4. Create development setup verification commands +5. Establish release and deployment preparation tools + +### Makefile Integration Commands + +**Standards Compliance Targets:** +- `make check-standards`: Check repository against PythonVibes standards (read-only) +- `make fix-standards`: Fix standards violations found (idempotent setup) + +**Essential Setup Targets:** +- `make setup-complete`: Full repository initialization from stub +- `make setup-structure`: Create directory structure and basic files +- `make setup-python`: Configure Python package structure +- `make setup-tools`: Install and configure development tools +- `make setup-docs`: Generate documentation framework +- `make setup-tests`: Create testing infrastructure +- `make verify-setup`: Verify complete setup functionality + +**Testing Targets:** +- `make test`: Run unit tests only (fast) +- `make test-all`: Run comprehensive test suite (tests + standards + quality) +- `make test-standards`: Run repository standards compliance tests +- `make test-coverage`: Analyze test coverage for specific issues + +**Development Workflow Targets:** +- `make install`: Install package in development mode +- `make lint`: Check code quality +- `make format`: Format code automatically +- `make clean`: Clean build artifacts and cache +- `make build`: Build package for distribution + +### Template Generation + +**pyproject.toml Template:** +```toml +[build-system] +requires = ["setuptools>=61.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "project-name" +version = "0.1.0" +description = "A well-structured Python project" +readme = "README.md" +requires-python = ">=3.8" +license = {text = "MIT"} +authors = [ + {name = "Author Name", email = "author@example.com"} +] +dependencies = [ + # Core dependencies +] + +[project.optional-dependencies] +dev = [ + "pytest>=7.0", + "black>=22.0", + "flake8>=5.0", + "mypy>=1.0", + "pre-commit>=2.20", +] + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.black] +line-length = 88 +target-version = ['py38'] + +[tool.flake8] +max-line-length = 100 +exclude = [".git", "__pycache__", "build", "dist"] + +[tool.mypy] +python_version = "3.8" +warn_return_any = true +warn_unused_configs = true +disallow_untyped_defs = true + +[tool.pytest.ini_options] +testpaths = ["tests"] +python_files = ["test_*.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +``` + +**Example Core Module Template:** +```python +"""Core functionality for project-name. + +This module provides the main functionality and serves as an example +of proper Python package structure following PythonVibes best practices. +""" + +from typing import Optional + + +class ExampleClass: + """Example class demonstrating proper structure and documentation. + + This class serves as a template for implementing core functionality + with proper type hints, docstrings, and error handling. + """ + + def __init__(self, name: str, value: Optional[int] = None) -> None: + """Initialize ExampleClass instance. + + Args: + name: The name identifier for this instance + value: Optional integer value (defaults to 0) + """ + self.name = name + self.value = value or 0 + + def process(self, input_data: str) -> str: + """Process input data and return formatted result. + + Args: + input_data: String data to process + + Returns: + Formatted string result + + Raises: + ValueError: If input_data is empty + """ + if not input_data.strip(): + raise ValueError("Input data cannot be empty") + + return f"{self.name}: {input_data} (value: {self.value})" + + +def example_function(text: str, multiplier: int = 1) -> str: + """Example function demonstrating proper function structure. + + Args: + text: Text to process + multiplier: Number of times to repeat (default: 1) + + Returns: + Processed text string + """ + return text * multiplier +``` + +### Error Prevention and Quality Assurance + +**Common Setup Issues to Avoid:** +- Missing __init__.py files preventing package imports +- Incorrect package naming (hyphens vs underscores) +- Missing or malformed pyproject.toml configuration +- Inconsistent tool configurations across files +- Missing virtual environment setup automation +- Inadequate .gitignore configuration for Python projects +- Missing essential documentation files +- Improper test directory structure + +**Quality Verification Steps:** +1. Verify package imports work correctly +2. Ensure all tools (black, flake8, mypy) run without errors +3. Confirm test discovery and execution works +4. **Run comprehensive test suite**: `make test-all` should pass completely +5. **Validate repository standards**: `make test-standards` must pass +6. Validate virtual environment creation and activation +7. Check that all Makefile targets execute successfully +8. Verify documentation files are properly formatted +9. Ensure CI/CD workflow templates are valid + +**Standards Testing Integration:** +- `make test-standards` checks for missing .gitignore and other essential files +- `make test-all` includes standards compliance as a prerequisite +- Standards violations cause test failures, preventing incomplete setups +- Automated detection of common repository setup issues + +### Response Guidelines + +#### For Standards Checking Mode: +1. **Thorough Analysis**: Systematically check all PythonVibes requirements +2. **Clear Reporting**: Provide specific, actionable feedback about violations +3. **Risk Assessment**: Categorize issues by impact and urgency +4. **Preservation Focus**: Never suggest changes that could break existing work +5. **Educational Value**: Explain why standards matter and their benefits +6. **Testing Integration**: Always recommend running `make test-all` to validate fixes +7. **Fail-Fast Principle**: Standards violations should cause test failures to prevent deployment + +#### For Standards Fixing Mode: +1. **Safety First**: Always preserve existing files and configurations +2. **Idempotent Operations**: Ensure setup can be run multiple times safely +3. **Minimal Intervention**: Only create what's missing, enhance what's incomplete +4. **Incremental Enhancement**: Build repository structure in logical phases +5. **Tool Integration**: Ensure all development tools work together harmoniously +6. **Documentation Focus**: Create clear, actionable documentation for contributors +7. **Automation Emphasis**: Set up automation to reduce manual setup burden +8. **Standards Compliance**: Follow PythonVibes best practices consistently +9. **Testing Priority**: Ensure testing infrastructure is robust and easy to use +10. **Future-Proofing**: Set up structure that can grow with project needs + +### Integration with Kaizen Principles + +**Continuous Improvement Setup:** +- Establish performance measurement hooks for development workflows +- Create optimization opportunities through automation +- Set up feedback collection mechanisms for development experience +- Build foundation for iterative improvement of development processes + +**Quality-First Approach:** +- Prioritize tool configuration that prevents common issues +- Establish quality gates through automated checking +- Create comprehensive testing foundation +- Set up documentation standards that scale with project growth + +### Response Format + +#### For Standards Checking Mode: +```markdown +## Repository Standards Analysis +[Current state assessment against PythonVibes requirements] + +## Compliance Report +[Detailed breakdown of standards compliance with specific violations] + +## Risk Assessment +[Categorization of issues by severity: critical, warning, suggestion] + +## Recommendations +[Specific actionable steps to achieve compliance] + +## Verification Commands +[Commands to run for detailed checking: make check-standards, make verify-setup] +``` + +#### For Standards Fixing Mode: +```markdown +## Repository Analysis +[Current state assessment and components that will be preserved vs. created] + +## Idempotent Setup Plan +[Phased approach to repository enhancement with safety considerations] + +## Changes Applied +[Specific files and configurations created or enhanced] + +## Preserved Elements +[Existing work that was maintained without modification] + +## Verification Results +[Commands run and results to confirm setup completion, including test-all success] + +## Testing Integration +[Confirmation that make test-all passes and includes standards compliance] + +## Next Steps +[Recommended actions for continued development and standards maintenance] +``` + +#### Additional Testing Requirements: + +**Standards Testing Integration:** +When setting up or checking repositories, always verify that: +1. `make test-standards` passes (checks .gitignore, essential files, tools) +2. `make test-all` includes standards checking as a prerequisite +3. Standards violations cause test failures (fail-fast principle) +4. All essential files are validated automatically + +**Continuous Integration Readiness:** +- Repository setup includes testing infrastructure that validates standards +- CI/CD workflows can use `make test-all` for comprehensive validation +- Standards compliance is treated as a required test, not optional check +- Missing .gitignore or other essential files will be caught automatically + +Remember: Your role is to transform repository stubs into production-ready Python projects that follow industry best practices, enable efficient development workflows, and provide a solid foundation for long-term project success. \ No newline at end of file