classroom-pilot 3.0.0a1

Classroom Pilot - Comprehensive automation suite for managing assignments

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)

# 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

# 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

# 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:

# 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

# 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

# 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:

# 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:

# 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:

# 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

# 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

# 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
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

---

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