Metadata-Version: 2.4
Name: ethiccode-representante
Version: 0.1.0
Summary: Automated SIES EduPlus Course Feedback with interactive TUI, CLI, and Biometric Security.
Author-email: EthicCode <contact@ethiccode.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/EthicCode/ethiccode-representante
Project-URL: Issues, https://github.com/EthicCode/ethiccode-representante/issues
Keywords: sies,eduplus,feedback,automation,playwright,tui,textual
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.50.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: keyring>=24.0.0
Provides-Extra: macos
Requires-Dist: pyobjc-framework-LocalAuthentication>=9.0; extra == "macos"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Dynamic: license-file

# 🌟 ethiccode-representante

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TUI: Textual](https://img.shields.io/badge/TUI-Textual-green.svg)](https://textual.textualize.io/)
[![Automation: Playwright](https://img.shields.io/badge/Automation-Playwright-orange.svg)](https://playwright.dev/)

> **Automated SIES EduPlus Course Feedback Submissions with a sleek modern Terminal UI (TUI), CLI support, and hardware biometric protection (macOS Touch ID & Windows Hello).**

---

## ✨ Features

- **🖥️ Gorgeous Interactive TUI**: Built with [Textual](https://textual.textualize.io/) featuring a live status dashboard, real-time log telemetry, progress indicators, password visibility toggles, and form verification stats.
- **🛡️ Biometric Security**:
  - **macOS Touch ID**: Native integration with Apple `LocalAuthentication` (Touch ID / Apple Watch / System Passcode) to lock and unlock saved credentials.
  - **Windows Hello**: Native integration with Windows Runtime `UserConsentVerifier` (Fingerprint / Facial Recognition / PIN).
- **🔐 Secure Credential Persistence**:
  - Remember username only (prompts for password on each run).
  - Remember username & password locally with PBKDF2 + AES-Fernet encryption or system Keyring (Keychain / Credential Manager).
  - One-click credential wiping (`--clear-creds` or via the TUI).
- **🎯 Precise Vue 3 + Vuetify Automation**:
  - Locates elements dynamically by visible text, labels, and placeholders rather than volatile auto-generated IDs.
  - Uses native `.click()` events to ensure Vue's reactivity properly registers radio selections.
  - **10/10 Form Validation**: Verifies that exactly 10 questions per faculty-subject match the chosen rating before proceeding. Aborts immediately if verification fails to prevent partial saves.
- **🛡️ Safety First (Dry-Run by Default)**:
  - Fills and verifies every single form but stops before the irreversible final submit.
  - Only submits permanently when explicitly confirmed.
- **⚡ Dual Mode (TUI & CLI)**: Run interactively with the graphical terminal interface or run headless via CLI scripts or cron jobs.

---

## 📦 Installation

Install `ethiccode-representante` via pip:

```bash
pip3 install ethiccode-representante
```

Install Playwright's Chromium browser dependency (one-time setup):

```bash
# Using the built-in helper:
ethiccode-representante --install-deps

# Or directly with playwright:
playwright install chromium
```

---

## 🚀 Usage

### 1. Interactive Terminal User Interface (TUI)

Simply run the command without arguments (or with `--tui`):

```bash
ethiccode-representante
```

*(You can also use the alias command: `sies-feedback`)*

The TUI provides:
- Credential inputs with Show/Hide password toggle.
- Toggles for "Remember Username", "Save Password", and "Require Touch ID / Windows Hello".
- Cycle selector (e.g. `2026-27` or leave blank for the first open cycle).
- Rating dropdown (`Excellent`, `Very Good`, `Good`, `Average`, `Below Average`).
- Dry-Run and Headless switches.
- Real-time streaming logs and form counter scoreboard.
- Abort button to safely stop execution at any time.

---

### 2. Command-Line Interface (CLI)

Run directly from the command line for fast or automated runs:

```bash
# Basic dry-run (verifies all forms without final submit)
ethiccode-representante -u 124A1018 -p "YourPassword" --dry-run

# Target a specific cycle and show browser window
ethiccode-representante -u 124A1018 -p "YourPassword" --cycle "2026-27" --no-headless

# Permanent submission (irreversible)
ethiccode-representante -u 124A1018 -p "YourPassword" --no-dry-run

# Save credentials with Biometric Protection
ethiccode-representante -u 124A1018 -p "YourPassword" --save-creds --biometric

# Use saved credentials on subsequent runs (prompts Touch ID / Windows Hello)
ethiccode-representante

# Wipe all locally stored credentials and configuration
ethiccode-representante --clear-creds

# Inspect current configuration and hardware biometric status
ethiccode-representante --show-config
```

Using environment variables instead of command-line arguments:

```bash
export SIES_PASSWORD="YourPassword"
ethiccode-representante -u 124A1018
```

---

## ⚙️ CLI Options & Flags

| Flag | Default | Description |
|---|---|---|
| `-u, --username` | Saved / Prompt | SIES portal username / roll number |
| `-p, --password` | Saved / Prompt | SIES portal password |
| `--password-env` | `SIES_PASSWORD` | Environment variable name for password |
| `--cycle` | First open | Substring filter for the feedback cycle (e.g. `2026-27`) |
| `--rating` | `Excellent` | Rating choice (`Excellent`, `Very Good`, `Good`, `Average`, `Below Average`) |
| `--dry-run / --no-dry-run` | `True` | Fill and verify without permanent irreversible submit |
| `--headless / --no-headless`| `True` | Run browser in background without visible window |
| `--slowmo` | `0` | Delay Playwright actions by N milliseconds |
| `--save-creds` | `False` | Store credentials securely for future runs |
| `--biometric / --no-biometric` | Auto-detect | Require Touch ID / Windows Hello before retrieving password |
| `--clear-creds` | `False` | Wipe saved credentials and configuration files |
| `--show-config` | `False` | Display current configuration and biometric status |
| `--install-deps` | `False` | Install Chromium browser binaries |
| `--tui` | `False` | Force launch interactive Textual TUI |

---

## 🔒 Security Architecture

- **Local Storage**: All files are stored under `~/.config/ethiccode-representante/` (or `%APPDATA%/ethiccode-representante` on Windows) with strict `0700` directory and `0600` file permissions.
- **Keyring & Fallback Vault**: Credentials are saved in the OS Keyring (macOS Keychain, Windows Credential Manager, or Linux SecretService). If unavailable, credentials are encrypted with AES-Fernet using PBKDF2HMAC key derivation tied to the machine salt.
- **Biometric Protection**:
  - On **macOS**, triggers the official `LocalAuthentication` prompt for Touch ID, Apple Watch, or system password challenge.
  - On **Windows**, triggers the `UserConsentVerifier` Windows Hello prompt.

---

## 🛠️ Development & Testing

```bash
# Clone the repository
git clone https://github.com/EthicCode/ethiccode-representante.git
cd ethiccode-representante

# Create virtual environment & install in editable mode with dev dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"

# Run unit tests
python3 -m unittest discover tests
```

---

## 📜 Disclaimer & License

This tool is designed to automate routine portal feedback for authorized students of SIES. Always ensure your feedback reflects your genuine experience before final submission. The authors are not responsible for unintended submissions.

Distributed under the [MIT License](LICENSE).
