Metadata-Version: 2.3
Name: classroom-pilot
Version: 3.0.0a1
Summary: Classroom Pilot - Comprehensive automation suite for managing assignments
License: MIT
Keywords: github,classroom,education,automation,cli
Author: Hugo Valle
Author-email: hugo.valle@example.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Systems Administration
Requires-Dist: click (>=8.1.3,<8.2.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: typer (>=0.9.0,<0.10.0)
Project-URL: Bug Reports, https://github.com/hugo-valle/classroom-pilot/issues
Project-URL: Documentation, https://github.com/hugo-valle/classroom-pilot#readme
Project-URL: Feature Requests, https://github.com/hugo-valle/classroom-pilot/issues
Project-URL: Homepage, https://github.com/hugo-valle/classroom-pilot
Project-URL: Repository, https://github.com/hugo-valle/classroom-pilot
Project-URL: Source, https://github.com/hugo-valle/classroom-pilot
Description-Content-Type: text/markdown

# Classroom Pilot

A modern Python CLI for automating GitHub Classroom assignment management with comprehensive workflow orchestration, repository discovery, and secret management capabilities.

## 🎯 Overview

Classroom Pilot provides instructors with a powerful command-line interface to automate GitHub Classroom assignment workflows, including:

- **🐍 Modern Python CLI** - Type-safe, intuitive command interface with rich output
- **📁 Universal file type support** - Works with any assignment file type (.py, .cpp, .sql, .md, .html, .ipynb, etc.)
- **🔍 Automated repository discovery** - Smart filtering and batch operations on student repositories
- **🔐 Batch secret management** - Secure token and secret distribution across repositories
- **🔄 Template synchronization** - Keep assignment templates in sync with GitHub Classroom
- **⚙️ Configuration-driven workflows** - Flexible, reusable assignment configurations
- **🛡️ Enterprise GitHub support** - Custom GitHub Enterprise and internal Git hosting
- **🎯 Instructor-focused filtering** - Automatically excludes instructor repositories from batch operations

## 📊 Project Status - Phase 3: Modular Architecture Complete ✅

**Current Release**: `v3.0.0-alpha.1` (Modular Architecture Implementation)

### ✅ Phase 2 Completed Features

#### 🐍 Complete Python CLI Architecture
- **✅ All 10 CLI commands implemented** with full bash script integration
- **✅ Typer-based CLI** with rich help output and shell completion
- **✅ Type-safe configuration** with comprehensive validation
- **✅ Modular command structure** for intuitive workflow management
- **✅ Global options** with dry-run, verbose, and configuration overrides
- **✅ Cross-platform compatibility** (Python 3.10+ on Windows/macOS/Linux)

#### 🏗️ Advanced Engineering
- **✅ Complete BashWrapper implementation** with all script integration
- **✅ Comprehensive error handling** with graceful fallbacks
- **✅ Configuration parsing** with environment variable expansion
- **✅ Custom GitHub host support** for enterprise environments
- **✅ Professional test suite** with 92.9% success rate (39/42 tests)

#### 🧪 Testing & Quality Assurance
- **✅ Comprehensive test coverage** with pytest framework
- **✅ Unit, integration, and comprehensive testing** 
- **✅ CI/CD pipeline** with GitHub Actions
- **✅ Multi-Python version support** (3.8-3.12)
- **✅ Professional code organization** following Python best practices

### 🎯 Phase 2 Status: COMPLETE ✅
- ✅ **Complete Python CLI implementation** with all functionality
- ✅ **Full backward compatibility** with existing bash scripts and configurations
- ✅ **Enhanced error handling** and user experience improvements
- ✅ **Cross-platform distribution** ready for production
- ✅ **Enterprise GitHub support** for custom hosting environments
- ✅ **Comprehensive documentation** and testing infrastructure

### 🚧 Upcoming Features

#### Phase 2 Completion
- **Web API foundation** for future dashboard integration
- **Plugin architecture** for extensible functionality
- **Enhanced analytics** and reporting capabilities
- **Integration testing** with real classroom environments

#### Phase 3: Web Interface & Advanced Features
- **React-based web dashboard** for visual assignment management
- **Real-time monitoring** and notification systems
- **Multi-classroom management** with role-based access
- **Advanced analytics** and student progress tracking

## 📦 Installation

### Option 1: Install via pip (Recommended)

```bash
# Install the latest version
pip install classroom-pilot

# Or install from source
pip install git+https://github.com/hugo-valle/classroom-pilot.git

# Verify installation
classroom-pilot --help
```

### Option 2: Install with Poetry

```bash
# Clone the repository
git clone https://github.com/hugo-valle/classroom-pilot.git
cd classroom-pilot

# Install with Poetry
poetry install

# Activate the environment
poetry shell

# Verify installation
classroom-pilot --help
```

### Option 3: Development Installation

```bash
# Clone and install in development mode
git clone https://github.com/hugo-valle/classroom-pilot.git
cd classroom-pilot

# Install in editable mode
pip install -e .

# Or install development dependencies
pip install -r requirements-dev.txt
```

### Requirements

- **Python 3.10+** (3.11+ recommended)
- **Git** for repository operations
- **GitHub CLI** (gh) for authentication
- **Bash/Zsh** shell environment

## 🚀 Quick Start

### 1. Configure Your Assignment

Create an assignment configuration file:

```bash
# Create assignment.conf
cat > assignment.conf << 'EOF'
# Assignment Configuration
CLASSROOM_URL="https://classroom.github.com/classrooms/123/assignments/456"
TEMPLATE_REPO_URL="https://github.com/instructor/assignment-template"
ASSIGNMENT_FILE="homework.py"

# GitHub Configuration
GITHUB_TOKEN_FILE="github_token.txt"
SECRETS_LIST="API_KEY,DATABASE_URL"
EOF
```

### 2. Run Commands

```bash
# Show all available commands
classroom-pilot --help

# Sync template to GitHub Classroom (dry-run first)
classroom-pilot --dry-run sync

# Discover student repositories
classroom-pilot discover

# Add secrets to student repositories
classroom-pilot secrets

# Run complete workflow
classroom-pilot run

# Get detailed help for any command
classroom-pilot sync --help
```

### 3. Configuration Options

```bash
# Use custom configuration file
classroom-pilot --config-file my-assignment.conf sync

# Enable verbose logging
classroom-pilot --verbose discover

# Skip confirmation prompts
classroom-pilot --yes secrets

# Combine options
classroom-pilot --config-file assignment.conf --dry-run --verbose run
```

## 🔧 Configuration

### Assignment Configuration File

Create an `assignment.conf` file with your assignment settings:

```bash
# Required: GitHub Classroom assignment URL
CLASSROOM_URL="https://classroom.github.com/classrooms/123/assignments/456"

# Required: Template repository URL
TEMPLATE_REPO_URL="https://github.com/instructor/assignment-template"

# Required: Assignment file to validate
ASSIGNMENT_FILE="homework.py"

# Optional: GitHub Enterprise support
GITHUB_HOSTS="github.enterprise.com,git.company.internal"

# Optional: Secrets management
GITHUB_TOKEN_FILE="github_token.txt"
SECRETS_LIST="API_KEY,DATABASE_URL,SECRET_TOKEN"

# Optional: Repository filtering
EXCLUDE_REPOS="template,example,demo"
INSTRUCTOR_REPOS="instructor-solution"
```

### Environment Variables

Override configuration with environment variables:

```bash
# Custom GitHub hosts
export GITHUB_HOSTS="git.company.internal,github.enterprise.com"

# GitHub token
export GITHUB_TOKEN="ghp_your_token_here"

# Custom assignment file
export ASSIGNMENT_FILE="main.cpp"

# Run with overrides
classroom-pilot sync
```

### Multi-line Arrays

Support for complex configuration arrays:

```bash
# Multi-line secrets list
SECRETS_LIST=(
    "API_KEY"
    "DATABASE_URL" 
    "SECRET_TOKEN"
    "WEBHOOK_SECRET"
)

# Multi-line exclude list
EXCLUDE_REPOS=(
    "template"
    "example" 
    "demo"
    "instructor-*"
)
```

## 📋 Commands Reference

### Main Commands

| Command | Description | Example |
|---------|-------------|---------|
| `run` | Execute complete workflow | `classroom-pilot run` |
| `sync` | Sync template to classroom | `classroom-pilot sync` |
| `discover` | Find student repositories | `classroom-pilot discover` |
| `secrets` | Manage repository secrets | `classroom-pilot secrets` |
| `assist` | Help students with issues | `classroom-pilot assist` |
| `version` | Show version information | `classroom-pilot version` |

### Global Options

| Option | Short | Description | Example |
|--------|-------|-------------|---------|
| `--dry-run` | `-n` | Preview without executing | `classroom-pilot --dry-run sync` |
| `--verbose` | `-v` | Enable detailed logging | `classroom-pilot --verbose discover` |
| `--config-file` | `-c` | Use custom config file | `classroom-pilot -c my.conf sync` |
| `--yes` | `-y` | Skip confirmation prompts | `classroom-pilot --yes secrets` |
| `--help` | | Show help information | `classroom-pilot --help` |

### Workflow Examples

```bash
# Complete assignment setup workflow
classroom-pilot --config-file assignment.conf run

# Sync template changes only
classroom-pilot --dry-run sync
classroom-pilot sync

# Update secrets for all students
classroom-pilot --verbose secrets

# Help specific students
classroom-pilot --config-file student-issues.conf assist

# Check what would happen
classroom-pilot --dry-run --verbose run
```

## 💡 Best Practices

### Development Workflow

- **Always test with `--dry-run`** before making changes
- **Use `--verbose`** for debugging configuration issues
- **Keep configuration files in version control** with your assignment
- **Use environment variables** for sensitive information
- **Test with single student first** using filtered configuration

### Configuration Management

- **Separate configs per assignment** for better organization
- **Use descriptive filenames** like `midterm-exam.conf`
- **Document custom GitHub hosts** in your assignment README
- **Validate URLs** before running batch operations

### Security Considerations

- **Store GitHub tokens securely** using `GITHUB_TOKEN_FILE`
- **Use environment variables** for sensitive configuration
- **Review `--dry-run` output** before executing changes
- **Limit repository access** with proper filtering
- **Audit secret distribution** using verbose logging

## 🛠️ Development

### Project Structure

```
classroom_pilot/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
├── cli.py               # Typer CLI implementation
├── config.py            # Configuration management
├── bash_wrapper.py      # Script execution wrapper
├── utils.py             # Utility functions
├── scripts/             # Bash scripts
│   ├── __init__.py
│   ├── *.sh             # Individual workflow scripts
└── docs/                # Documentation
```

### Contributing

```bash
# Clone and setup development environment
git clone https://github.com/hugo-valle/classroom-pilot.git
cd classroom-pilot

# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .

# Run tests
make test              # Quick functionality tests
make test-unit         # Full pytest unit tests
pytest tests/ -v       # Run tests directly

# Run comprehensive tests
make test-full
python tests/test_comprehensive.py

# Format code
black classroom_pilot/
isort classroom_pilot/

# Type checking
mypy classroom_pilot/

# Create feature branch
git checkout -b feature/new-feature
```

### Architecture

- **Modern Python CLI** built with Typer for rich interaction
- **Configuration-driven** with validation and environment expansion  
- **Bash script compatibility** through wrapper execution
- **Cross-platform support** with proper path handling
- **Enterprise GitHub support** with custom host validation
- **Type safety** with comprehensive type annotations

## 📞 Support

- **Documentation**: [GitHub Repository](https://github.com/hugo-valle/classroom-pilot)
- **Issues**: [GitHub Issues](https://github.com/hugo-valle/classroom-pilot/issues)
- **Discussions**: [GitHub Discussions](https://github.com/hugo-valle/classroom-pilot/discussions)

---

---

**Classroom Pilot** - Streamlining GitHub Classroom assignment management through modern automation.

