ismis-helper/README.md

ISMIS Helper

A lightweight Firefox / Chrome extension for the USC ISMIS student portal that:

• Auto-fills and auto-submits your login.
• Auto-accepts the privacy-policy modal.
• Exports a Study Load PDF that matches the official layout — bundled Segoe UI fonts, the USC logo, the course table, and the units total.

One codebase builds for both browsers (see Build).

Install

Temporary/development install. For distribution, publish the built zips to Firefox AMO and the Chrome Web Store — they are store-ready.

Firefox (load temporary add-on)

1. Build the Firefox variant (or download ismis-helper-firefox.zip from CI):

   node scripts/build.js firefox
   

   The output is at dist/ismis-helper-firefox.zip (unzip it, or use dist/firefox/ directly).
2. Open about:debugging in Firefox.
3. Click This Firefox → Load Temporary Add-on….
4. Select dist/firefox/manifest.json.
5. Open https://ismis.usc.edu.ph and use the extension.

Chrome (load unpacked)

1. Build the Chrome variant (or download ismis-helper-chrome.zip from CI):

   node scripts/build.js chrome
   

2. Unzip dist/ismis-helper-chrome.zip (or use dist/chrome/ directly).
3. Open chrome://extensions in Chrome.
4. Enable Developer mode (toggle, top-right).
5. Click Load unpacked and select the unzipped dist/chrome folder.
6. Open https://ismis.usc.edu.ph and use the extension.

For a persistent install, package and publish via Firefox AMO / Chrome Web Store with the same built zips.

Distribute to real users

Firefox (self-hosted, temporary)

Note: Firefox blocks unsigned extensions for normal installs. The proper fix is to sign the add-on via addons.mozilla.org (AMO) and publish it there (or self-host a signed .xpi). AMO is currently under maintenance, so until it returns, the only way to install the unsigned build is to lower Firefox's signing check on each user's machine. This is a per-user browser setting and is not suitable for a broad audience — use it for personal / small-group use.

1. Build the Firefox variant (or download ismis-helper-firefox.zip from a release):

   node scripts/build.js firefox
   

2. In Firefox, open about:config and accept the warning.
3. Search for xpinstall.signatures.required and set it to false.
4. Restart Firefox for the change to take effect.
5. Install the add-on from the release zip: drag ismis-helper-firefox.zip into Firefox (or File → Open File… and select it).

When AMO is back online, prefer the signed route: publish the same zip to AMO (or sign it with web-ext sign) so users install it normally without touching about:config.

Chrome (self-hosted)

Chrome does not require signing for normal installs. Users can install the built ismis-helper-chrome.zip directly:

1. Download ismis-helper-chrome.zip from a release and unzip it.
2. Open chrome://extensions, enable Developer mode, and click Load unpacked.
3. Select the unzipped folder.

For a store experience, publish the same zip to the Chrome Web Store (one-time $5 developer registration).

Features

• Saved login profiles (stored in browser.storage.local) — only one enabled at a time, with a master on/off toggle.
• One-click Download PDF button on the Study Load page, plus CSV / Excel / JSON / Next Up export buttons.
• PDF settings in the popup:
  • Truncate long course descriptions to match the official PDF (default on).
  • Show/hide Year Level, and set a custom Year Level value.
  • Year Level mode: Auto (recommended), Use custom value, or Profile value only.
• Smart Year Level: for the semester being printed, Auto derives the standing from remaining units (Student Prospectus total − Lacking Subjects, reflecting units actually passed) or, failing that, from the View Grades history. Custom value overrides; the profile-scraped value is the fallback.
• Live progress indicator: during any export a status bar below the buttons shows the current step (reading table, fetching course descriptions i/N, profile, year level, building file) with a progress percentage.
• Next Up import: the Next Up export writes CSV in the exact column contract the Raycast Next Up extension accepts (title, courseCode, days, startTime, endTime, room, units, professorName), so schedules drop straight into the app.
• Bundled Segoe UI fonts for a 1:1 look with the official document.
• Builds and packages automatically via Gitea Actions (zips + versioned releases with a signed .xpi).

Build

Requires Node.js (the build.js script itself is dependency-free; npm install is only needed to run the tests).

npm install                     # dev deps for tests
npm test                        # run the test suite
npm run build                   # build both -> dist/*.zip
node scripts/build.js all       # build both explicitly
node scripts/build.js chrome    # just chrome
node scripts/build.js all --version 1.3.0   # versioned zips

CI (Gitea Actions): on every push, both zips are built, tests run, and the zips are uploaded as artifacts. When you push a v* tag (e.g. v1.3.0), it additionally creates a Gitea Release with both versioned zips attached.

Settings

Open the extension popup to:

• Manage login profiles (add / edit / enable).
• Toggle the master on/off switch.
• Set PDF options: truncate descriptions, show/hide Year Level, Year Level mode, and a custom Year Level value.

The Study Load page gets a button row — Download PDF, CSV, Excel, JSON, and Next Up — next to the total-units line.

Data & privacy

• Profile passwords are encrypted at rest with Web Crypto AES-GCM (256-bit). The key lives in browser.storage.local so it survives restarts. This removes the plaintext-password smell from storage; it is NOT strong protection against an attacker who can read both the storage and the extension source — this extension only talks to the school portal, never any third-party server.
• This is a personal-use helper for the university portal; use it only with your own account.

Development

See AGENTS.md for the repository layout, build model, and coding conventions for this project.