Merge pull request #50 from VectorInstitute/add_admin_module

Add setup participants admin sub-command

Author: amrit110

docs/cli.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-The `aieng-platform-onboard` package provides a command-line tool for bootcamp participant onboarding, authentication, and environment setup.
+The `aieng-platform-onboard` package provides a command-line tool for bootcamp participant onboarding, authentication, environment setup, and admin operations.
 
 ## Installation
 
@@ -14,6 +14,10 @@ pip install aieng-platform-onboard
 
 Main command for onboarding bootcamp participants with team-specific API keys.
 
+### `onboard admin`
+
+Admin commands for managing participants and teams.
+
 #### Usage
 
 ```bash
@@ -40,6 +44,66 @@ View onboarding status for all participants (requires admin credentials):
 onboard --admin-status-report --gcp-project coderd
 ```
 
+## Admin Commands
+
+### `onboard admin setup-participants`
+
+Setup participants and teams from CSV file.
+
+#### Usage
+
+```bash
+onboard admin setup-participants <csv_file> [--dry-run]
+```
+
+#### Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `csv_file` | Path to CSV file | Yes |
+
+#### CSV Format
+
+Required columns:
+- `github_handle` - GitHub username
+- `team_name` - Team name
+
+Optional columns:
+- `email` - Email address
+- `first_name` - First name
+- `last_name` - Last name
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Validate and preview changes without modifying Firestore |
+
+#### Examples
+
+**Setup participants from CSV:**
+```bash
+onboard admin setup-participants participants.csv
+```
+
+**Dry run (validate only):**
+```bash
+onboard admin setup-participants participants.csv --dry-run
+```
+
+**Sample CSV:**
+```csv
+github_handle,team_name,email,first_name,last_name
+alice,team-alpha,[email protected],Alice,Smith
+bob,team-alpha,[email protected],Bob,Jones
+charlie,team-beta,[email protected],Charlie,Brown
+```
+
+#### Requirements
+
+- Admin credentials (service account or gcloud auth)
+- Firestore write access
+
 ## Options
 
 ### Required (for participant onboarding)
@@ -133,11 +197,21 @@ onboard \
 ### Admin Status Report
 
 ```bash
-# Requires admin credentials (service account or gcloud auth)
+# Requires admin credentials
 gcloud auth application-default login
 onboard --admin-status-report --gcp-project coderd
 ```
 
+### Setup Participants
+
+```bash
+# Setup participants from CSV
+onboard admin setup-participants config/participants.csv
+
+# Validate CSV without making changes
+onboard admin setup-participants config/participants.csv --dry-run
+```
+
 ## Generated Files
 
 ### .env File
@@ -182,4 +256,11 @@ source .env
   gcloud auth application-default login
   ```
 - Or set `GOOGLE_APPLICATION_CREDENTIALS` to service account key path
-- Verify you have Firestore read access for the project
+- Verify you have Firestore read/write access for the project
+
+### CSV Validation Errors
+
+- Check CSV has required columns: `github_handle`, `team_name`
+- Verify GitHub handles are valid (alphanumeric and hyphens, max 39 chars)
+- Ensure team names are valid (alphanumeric, hyphens, underscores)
+- Check for duplicate GitHub handles

scripts/admin/setup_teams.py

@@ -12,7 +12,7 @@
 from datetime import datetime, timezone
 from pathlib import Path
 
-from google.cloud import firestore
+from google.cloud import firestore  # type: ignore[attr-defined]
 from rich.panel import Panel
 from rich.progress import Progress, SpinnerColumn, TextColumn
 from rich.table import Table

scripts/collect_coder_analytics.py

@@ -21,7 +21,7 @@
 
 
 try:
-    from google.cloud import firestore, storage
+    from google.cloud import firestore, storage  # type: ignore[attr-defined]
 except ImportError:
     print("Error: google-cloud-storage or google-cloud-firestore not installed.")
     print("Run: pip install google-cloud-storage google-cloud-firestore")

services/token-service/main.py

@@ -14,7 +14,7 @@
 import jwt
 from firebase_admin import auth, credentials
 from flask import Flask, request
-from google.cloud import firestore
+from google.cloud import firestore  # type: ignore[attr-defined]
 
 
 # Initialize Flask app

src/aieng_platform_onboard/admin/__init__.py

@@ -0,0 +1,6 @@
+"""Admin commands for aieng-platform-onboard."""
+
+from aieng_platform_onboard.admin.cli import main as admin_main
+
+
+__all__ = ["admin_main"]

src/aieng_platform_onboard/admin/cli.py

@@ -0,0 +1,61 @@
+"""Admin CLI dispatcher for aieng-platform-onboard."""
+
+import argparse
+import sys
+
+from aieng_platform_onboard.admin.setup_participants import (
+    setup_participants_from_csv,
+)
+
+
+def main() -> int:
+    """
+    Admin CLI entry point for admin commands.
+
+    Returns
+    -------
+    int
+        Exit code (0 for success, 1 for failure).
+    """
+    parser = argparse.ArgumentParser(
+        prog="onboard admin",
+        description="Admin commands for managing bootcamp participants and teams",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        help="Admin command to run",
+        required=True,
+    )
+
+    # setup-participants subcommand
+    setup_participants_parser = subparsers.add_parser(
+        "setup-participants",
+        help="Setup participants and teams from CSV file",
+        description="Load participants and teams from CSV into Firestore",
+    )
+    setup_participants_parser.add_argument(
+        "csv_file",
+        type=str,
+        help="Path to CSV file with columns: github_handle, team_name, email (optional), first_name (optional), last_name (optional)",
+    )
+    setup_participants_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate and show what would be done without making changes",
+    )
+
+    args = parser.parse_args()
+
+    # Route to appropriate command handler
+    if args.command == "setup-participants":
+        return setup_participants_from_csv(args.csv_file, dry_run=args.dry_run)
+
+    # Should never reach here due to required=True
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())