vsuee-skill

v1.0.0

Published

a month ago

High-speed CLI toolkit and AI agent skill for the Visayas State University E-Learning Environment (VSUEE Moodle).

0High
0Medium
0Low

cedric_devon

m1vj

vsuee vsuee-skill vsu moodle elearning agent-skill ai-agent calendar-export sync downloader automation playwright

VSUEE Skill — Visayas State University E-Learning Toolkit & Agent Skill

High-performance CLI toolkit and AI agent skill for the Visayas State University E-Learning Environment (VSUEE) running Moodle at elearning.vsu.edu.ph.

Engineered for students, researchers, and autonomous coding agents (Gemini CLI, Codex, Claude Code, Cursor) across macOS, Linux, and Windows who need instant access to course syllabi, assignments, lecture slides, submission rubrics, calendar deadlines, and last-minute instructor updates without fighting slow web interfaces.

Highlights

⚡ Direct HTTP/AJAX Engine: Sub-second queries for courses, assignments, quizzes, and forum threads without heavy browser rendering overhead.
🔄 Intelligent Snapshot Diffing: Detects newly uploaded lecture notes, unhidden exam topics, and moved deadlines with surgical change reporting (vsuee sync, vsuee diff).
📅 RFC 5545 iCalendar Export: Exports all course deadlines and quiz windows into standard .ics files with 24-hour VALARM notifications for Apple Calendar, Google Calendar, and Microsoft Outlook.
🚀 Parallel Batch Downloads: High-speed concurrent downloads with bounded worker pools, progress indicators, MIME type detection, and incremental deduplication.
🔐 Machine-Bound AES-256-GCM Session Storage: Encrypts credentials and sessions with a machine-derived key stored at ~/.config/vsuee/session.json (chmod 0600). Automatically handles background re-authentication on 6-hour sliding window timeouts.
📸 Targeted Visual Proof: Playwright fallback to capture crisp element screenshots (--selector) or full-page captures for quiz timers, submission tables, and grades.
🤖 Agent-Ready Native Skill: Includes a standardized SKILL.md specification enabling AI agents to read lecture pages, inspect rubrics, verify submission statuses, and monitor updates autonomously.
🌐 Cross-Platform: Fully supported across macOS, Linux, and Windows with zero platform lock-in.

Installation

Prerequisites

Node.js >= 18.0.0
(Optional) playwright for browser mode / screenshot capture

Universal Installation (macOS, Linux, Windows)

Option 1: Global Link (Recommended for all platforms)

Clone the repository to any directory of your choice and link it globally:

git clone https://github.com/M1Vj/vsuee-skill.git
cd vsuee-skill
npm link

The vsuee executable will now be available globally in your PATH across any terminal or shell.

Option 2: Direct Symlink (macOS & Linux)

# Clone to your preferred directory (e.g. ~/.local/share/vsuee or ~/vsuee-skill)
git clone https://github.com/M1Vj/vsuee-skill.git ~/vsuee-skill
cd ~/vsuee-skill

# Link executable to your local bin directory:
mkdir -p ~/.local/bin
ln -sf "$(pwd)/bin/vsuee.mjs" ~/.local/bin/vsuee

# Ensure ~/.local/bin is in your PATH (e.g. in ~/.bashrc or ~/.zshrc)

Option 3: Global npm Package Install

npm install -g .

To enable browser-based screenshots and interactive login fallback:

npm install playwright

Quick Start

1. Authenticate

# Standard interactive login (saves encrypted credentials for seamless auto-relogin)
vsuee login

# Or open interactive browser to log in visually:
vsuee login-browser

# Verify connection health
vsuee status

2. View Courses & Deadlines

# List enrolled courses with progress
vsuee courses

# View upcoming deadlines and timeline events
vsuee timeline

# Export upcoming deadlines to Apple/Google Calendar (.ics)
vsuee calendar --export

3. Check for New Updates

# Sync courses and check if instructors uploaded slides or changed deadlines
vsuee sync

# Or compare remote portal live against local baseline
vsuee diff --live

AI Agent Skill Setup

vsuee includes a portable agent skill specification following the open agent skill standard.

For Gemini CLI / Antigravity

mkdir -p ~/.gemini/config/plugins/vsuee/skills/vsuee
cp skills/vsuee/SKILL.md ~/.gemini/config/plugins/vsuee/skills/vsuee/SKILL.md

For Codex CLI

mkdir -p ~/.codex/skills/vsuee
cp skills/vsuee/SKILL.md ~/.codex/skills/vsuee/SKILL.md

For Claude Code

mkdir -p ~/.claude/skills/vsuee
cp skills/vsuee/SKILL.md ~/.claude/skills/vsuee/SKILL.md

Once installed, agents will automatically discover vsuee commands when asked questions like:

"Check my upcoming deadlines on VSU eLearning."
"Did my professor upload any new slides today?"
"Download all lecture PDFs for CSci 144."
"Show me the rubric and submission status for Assignment 3."
"Export my VSU exam and quiz schedule to Apple Calendar."

Command Reference

1. Authentication & Session Management

2. Courses & Syllabus Inspection

3. Deadlines, Assignments & Grades

4. File & Media Downloads

5. Change Detection & Monitoring

6. Visual Inspection & Screenshots

(Requires playwright)

Common Workflows & Runbooks

1. Catching Last-Minute Instructor Uploads

Instructors frequently upload lecture notes or problem sets right before class:

# 1. Check for differences
vsuee sync

# 2. If new files were found, download them automatically
vsuee sync --download-new

2. Exporting Deadlines to Apple or Google Calendar

# Export all upcoming course deadlines and quiz windows to .ics
vsuee calendar --export ~/Downloads/vsuee_calendar.ics

# Open directly on macOS to import into Apple Calendar
open ~/Downloads/vsuee_calendar.ics

3. Downloading Course Materials for Offline Study

# Download all lecture slides (PPTX and PDF) for course 1610 with 4 parallel streams
vsuee download 1610 --type pdf --dest ~/Documents/CSci144 -c 4
vsuee download 1610 --type pptx --dest ~/Documents/CSci144 -c 4

4. Background Monitoring Daemon

Keep your local course mirror updated 24/7 without terminal windows:

# Check every 15 minutes, download new files, and trigger macOS desktop notifications
vsuee daemon install --interval 15 --download-new

# Check status anytime
vsuee daemon status

Security & Privacy

Local-Only Storage: All sessions, hashes, and configuration live in ~/.config/vsuee/. No telemetry, analytics, or third-party servers are used.
Machine-Bound AES-256-GCM Encryption: Stored credentials are encrypted with a 256-bit key derived deterministically from the local machine's identity and user context. Encrypted payloads cannot be decrypted if copied to another machine.
Strict File Permissions: The session and snapshot files are written with 0600 permissions (read/write by the owner only).
Credential Masking: Command logs, diff summaries, and JSON outputs never expose plaintext passwords.

Academic Integrity

Strict Quiz & Exam Boundary: In adherence with the Visayas State University Student Honor Code and AI safety principles, vsuee strictly disables and rejects any automated quiz-answering, question solving, or test-taking automations. Quizzes are strictly inspectable for deadlines, open/close windows, and syllabus review only.
Assignment Submissions: Legitimate student-authored assignment files and online text responses can be submitted via vsuee submit. To prevent accidental or premature submissions, submissions default to draft mode, require interactive confirmation ([y/N]), verify SHA-256 hashes, and log local receipts in ~/.config/vsuee/submissions.log.
Confirmation Gate: Grade-impacting actions always require explicit user confirmation.

Development & Testing

The test suite contains 72 tests covering authentication, session auto-relogin, course parsing, module reading, parallel downloads, calendar .ics generation, assignment submissions, snapshot diffing, and browser screenshots.

# Run unit tests (offline, no network or credentials needed)
npm run test:unit

# Run full test suite (includes live integration tests when authenticated)
npm test

# Run live integration tests against portal
npm run test:live