# ISMIS Helper

A lightweight **[Firefox](https://addons.mozilla.org/)** / **[Chrome](https://chromewebstore.google.com/)**
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](#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):
   ```bash
   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):
   ```bash
   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):
   ```bash
   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](https://github.com/) 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).

```bash
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

- Auto-login stores your portal credentials **in plaintext** on your own device.
- This is a personal-use helper for the university portal; use it only with your
  own account.

## Development

See [`AGENTS.md`](AGENTS.md) for the repository layout, build model, and coding
conventions for this project.