Compare commits
44
Commits
v1.3.0
..
e11a7aad83
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e11a7aad83 | ||
|
|
cb47d6faac | ||
|
|
106900860a | ||
|
|
b3b4495427 | ||
|
|
79d58f994d | ||
|
|
161f540e40 | ||
|
|
79702cb847 | ||
|
|
2fa4064c7c | ||
|
|
4ef392423a | ||
|
|
e6249ae330 | ||
|
|
51d467fbe7 | ||
|
|
52360ab559 | ||
|
|
c75850da2e | ||
|
|
17aeab9592 | ||
|
|
053c6aaa98 | ||
|
|
57c4b6f204 | ||
|
|
792974bd32 | ||
|
|
631ff4e9d2 | ||
|
|
1537881ebc | ||
|
|
8bcfee341c | ||
|
|
b09e0cea76 | ||
|
|
bf4e7170a6 | ||
|
|
cb2beecc0e | ||
|
|
d6bacef1ec | ||
|
|
9f02bebdea | ||
|
|
0128476c37 | ||
|
|
f7e72ddff3 | ||
|
|
2cf3b71e27 | ||
|
|
8020a24655 | ||
|
|
78570c4088 | ||
|
|
4d7ff1a0e7 | ||
|
|
a072edd6d1 | ||
|
|
d12a7da646 | ||
|
|
c4f379ff1c | ||
|
|
0d29f0116a | ||
|
|
cefad72416 | ||
|
|
544d4aab1a | ||
|
|
5a9c185a48 | ||
|
|
94d9b7a879 | ||
|
|
3c409ea048 | ||
|
|
06d9a4be11 | ||
|
|
b920bf6f61 | ||
|
|
a57d7ac44c | ||
|
|
a0178aa0ab |
@@ -1,73 +0,0 @@
|
|||||||
name: build-extension
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [feat/ismis-helper, prod]
|
|
||||||
tags: ['v*']
|
|
||||||
pull_request:
|
|
||||||
|
|
||||||
# Ensure the job token can create releases and upload assets.
|
|
||||||
permissions:
|
|
||||||
contents: write
|
|
||||||
releases: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Set up Node
|
|
||||||
uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: 20
|
|
||||||
|
|
||||||
- name: Install dev dependencies
|
|
||||||
run: npm ci || npm install
|
|
||||||
|
|
||||||
- name: Install PyMuPDF (PDF text assertions)
|
|
||||||
run: |
|
|
||||||
python3 -m venv /tmp/venv
|
|
||||||
/tmp/venv/bin/pip install --quiet pymupdf
|
|
||||||
echo "/tmp/venv/bin" >> "$GITHUB_PATH"
|
|
||||||
|
|
||||||
- name: Run tests
|
|
||||||
run: npm test
|
|
||||||
|
|
||||||
- name: Build both variants
|
|
||||||
run: node scripts/build.js all
|
|
||||||
|
|
||||||
- name: Upload zip artifacts
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: ismis-helper-zips
|
|
||||||
path: dist/*.zip
|
|
||||||
if-no-files-found: error
|
|
||||||
|
|
||||||
- name: Publish release on version tag
|
|
||||||
if: startsWith(github.ref, 'refs/tags/v')
|
|
||||||
# Gitea-native release: softprops/action-gh-release targets GitHub's API
|
|
||||||
# and fails on Gitea (405). Instead we call the Gitea API directly with
|
|
||||||
# the runner-provided GITHUB_TOKEN and GITHUB_API_URL.
|
|
||||||
env:
|
|
||||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
run: |
|
|
||||||
set -euo pipefail
|
|
||||||
REPO="${{ github.repository }}"
|
|
||||||
TAG="${{ github.ref_name }}"
|
|
||||||
API="${GITHUB_API_URL:-https://git.ranio.xyz/api/v1}"
|
|
||||||
# Create the release for the tag
|
|
||||||
RELEASE_JSON=$(curl -sS -X POST \
|
|
||||||
-H "Authorization: token ${GITHUB_TOKEN}" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d "{\"tag_name\":\"${TAG}\",\"name\":\"${TAG}\",\"body\":\"ISMIS Helper ${TAG}\"}" \
|
|
||||||
"${API}/repos/${REPO}/releases")
|
|
||||||
RELEASE_ID=$(echo "${RELEASE_JSON}" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
|
|
||||||
# Attach both zips as release assets
|
|
||||||
for f in dist/*.zip; do
|
|
||||||
curl -sS -X POST \
|
|
||||||
-H "Authorization: token ${GITHUB_TOKEN}" \
|
|
||||||
-F "attachment=@${f}" \
|
|
||||||
"${API}/repos/${REPO}/releases/${RELEASE_ID}/assets?name=$(basename "${f}")"
|
|
||||||
done
|
|
||||||
@@ -1,4 +1 @@
|
|||||||
node_modules/
|
node_modules/
|
||||||
|
|
||||||
docs/
|
|
||||||
dist/
|
|
||||||
|
|||||||
@@ -1,86 +0,0 @@
|
|||||||
# ISMIS Helper — Agent Guide
|
|
||||||
|
|
||||||
Guidance for AI coding agents and contributors working in this repository.
|
|
||||||
|
|
||||||
## What this is
|
|
||||||
|
|
||||||
A Firefox/Chrome **MV3** extension that automates the USC ISMIS student portal
|
|
||||||
(`ismis.usc.edu.ph`): auto-login, privacy-policy auto-accept, and a **Study Load
|
|
||||||
PDF** export that visually matches the official document (bundled **Segoe UI**
|
|
||||||
fonts, USC logo, course table, units total).
|
|
||||||
|
|
||||||
No build step is required for the source itself; `scripts/build.js` only packages
|
|
||||||
the two browser variants into `dist/`.
|
|
||||||
|
|
||||||
## Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install # dev deps (only needed for tests)
|
|
||||||
npm test # run the test suite (node --test)
|
|
||||||
node scripts/build.js all # build both browser zips -> dist/
|
|
||||||
node scripts/build.js firefox # build just firefox
|
|
||||||
node scripts/build.js chrome # build just chrome
|
|
||||||
node scripts/build.js all --version 1.3.0 # versioned zips
|
|
||||||
npm run build # shorthand for `node scripts/build.js all`
|
|
||||||
```
|
|
||||||
|
|
||||||
Never edit anything under `dist/` — it is generated and gitignored.
|
|
||||||
|
|
||||||
## Repo layout
|
|
||||||
|
|
||||||
- `manifest.json` — **Firefox** manifest (the single source of truth). The Chrome
|
|
||||||
manifest is derived at build time.
|
|
||||||
- `background.js` — message handler; builds the PDF via `pdf.js` and downloads it.
|
|
||||||
Also has the cross-browser `browser.*`/`chrome.*` alias shim at the top.
|
|
||||||
- `content.js` — runs on ismis.usc.edu.ph: auto-login, privacy modal auto-accept,
|
|
||||||
scrapes the study load, injects the on-page **Download PDF** button.
|
|
||||||
- `parsers.js` — pure HTML-scraping helpers (study load table, profile page,
|
|
||||||
offered courses, filtering/summing).
|
|
||||||
- `pdf.js` — builds the PDF; exports `buildStudyLoadPdf` plus formatting helpers
|
|
||||||
(`compactProgram`, `formatSchedule`, `formatFullName`, `formatTeacher`,
|
|
||||||
`deriveDateRange`, `truncateToWidth`).
|
|
||||||
- `popup.html` / `popup.js` / `popup.css` — settings UI (profiles, master toggle,
|
|
||||||
PDF settings like truncation and Year Level).
|
|
||||||
- `libs/` — vendored `pdf-lib.min.js` and `fontkit.min.js` (needed to embed the
|
|
||||||
custom Segoe UI fonts).
|
|
||||||
- `assets/` — the transparent PNG logo and `fonts/Segoe-UI*.ttf`.
|
|
||||||
- `icons/` — 16/32/48/128 extension icons.
|
|
||||||
- `scripts/build.js` — zero-dependency packaging script for both browsers.
|
|
||||||
- `.gitea/workflows/build.yml` — Gitea Actions: builds + tests on push, creates a
|
|
||||||
Gitea Release with both zips when a `v*` tag is pushed.
|
|
||||||
- `test/` — `node --test` suite (`pdf.test.js`, `parsers.test.js`).
|
|
||||||
|
|
||||||
## Build model (Firefox vs Chrome)
|
|
||||||
|
|
||||||
- The **root is the Firefox source**: `manifest.json` uses `background.scripts`
|
|
||||||
(multiple files) and `browser.*` APIs.
|
|
||||||
- The **Chrome build** derives a manifest with
|
|
||||||
`"background": { "service_worker": "background.chrome.js" }` and assembles that
|
|
||||||
single worker by concatenating, in order:
|
|
||||||
`libs/fontkit.min.js` → `libs/pdf-lib.min.js` → `pdf.js` → `background.js`.
|
|
||||||
- The cross-browser shim (top of `background.js`, `content.js`, `popup.js`) aliases
|
|
||||||
`browser` to `chrome` when the former is absent. It is a no-op in Firefox.
|
|
||||||
- `scripts/build.js` **excludes** `test/`, `docs/`, `scripts/`, `dist/`, and
|
|
||||||
`.git` from the packaged output.
|
|
||||||
|
|
||||||
## Conventions & constraints
|
|
||||||
|
|
||||||
- Plain ES5+ JavaScript. No framework, no bundler, no build step for the source.
|
|
||||||
- Use Promise-based `browser.*` APIs (Chrome MV3 supports `browser.*`; the shim
|
|
||||||
covers builds that only expose `chrome.*`).
|
|
||||||
- Login profiles are stored **plaintext** in `browser.storage.local`. At most one
|
|
||||||
profile is enabled at a time; a master `enabled` toggle disables all behavior.
|
|
||||||
- The on-page **Download PDF** button must never touch another window's DOM; it
|
|
||||||
sends a message to the background which downloads via
|
|
||||||
`browser.downloads.download({ saveAs: true })` (blob → object URL).
|
|
||||||
- If you change `pdf.js` layout constants, verify against the reference PDF
|
|
||||||
(`/Users/adrianbonpin/Downloads/BSIT - Y3S1 - Study Load.pdf`) and re-check the
|
|
||||||
position measurements, since offsets can be font-metric dependent.
|
|
||||||
- Keep `docs/` and `dist/` out of git (they are ignored).
|
|
||||||
|
|
||||||
## Workflow
|
|
||||||
|
|
||||||
1. Run `npm test` before and after changes.
|
|
||||||
2. Build (`npm run build`) to make sure both variants assemble.
|
|
||||||
3. Manually load `dist/firefox` in Firefox (`about:debugging`) and `dist/chrome`
|
|
||||||
in Chrome (`chrome://extensions`) to verify PDF generation.
|
|
||||||
@@ -1,128 +0,0 @@
|
|||||||
# 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.
|
|
||||||
- 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.
|
|
||||||
- **Bundled Segoe UI fonts** for a 1:1 look with the official document.
|
|
||||||
- Builds and packages automatically via Gitea Actions (zips + versioned releases).
|
|
||||||
|
|
||||||
## 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`, custom Year Level.
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
+4
-30
@@ -1,36 +1,9 @@
|
|||||||
'use strict';
|
'use strict';
|
||||||
// Cross-browser API namespace. Firefox provides Promise-based `browser.*`;
|
|
||||||
// Chrome MV3 exposes `browser.*` too, but some builds only populate the
|
|
||||||
// `chrome.*` global. Alias to whichever is present.
|
|
||||||
if (typeof browser === 'undefined' || browser == null) {
|
|
||||||
var browser = (typeof chrome !== 'undefined' ? chrome : {});
|
|
||||||
}
|
|
||||||
|
|
||||||
function errMsg(err) {
|
function errMsg(err) {
|
||||||
return String((err && err.message) || err);
|
return String((err && err.message) || err);
|
||||||
}
|
}
|
||||||
|
|
||||||
// Build a download URL from PDF bytes. Firefox's background is a real page
|
|
||||||
// (URL.createObjectURL available) and supports blob: URLs in downloads.
|
|
||||||
// Chrome MV3 runs the background as a service worker where URL.createObjectURL
|
|
||||||
// is NOT available, but its downloads API accepts base64 data: URLs.
|
|
||||||
// Firefox rejects data: URLs in browser.downloads.download with
|
|
||||||
// "Access denied for URL data:...", so pick per-browser.
|
|
||||||
function buildDownloadUrl(bytes) {
|
|
||||||
if (typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function') {
|
|
||||||
const blob = new Blob([bytes], { type: 'application/pdf' });
|
|
||||||
return URL.createObjectURL(blob);
|
|
||||||
}
|
|
||||||
// Fallback: Chrome MV3 service worker. PDFs here are small (~150KB), well
|
|
||||||
// within data-URL length limits.
|
|
||||||
let binary = '';
|
|
||||||
const chunk = 0x8000;
|
|
||||||
for (let i = 0; i < bytes.length; i += chunk) {
|
|
||||||
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + chunk));
|
|
||||||
}
|
|
||||||
return 'data:application/pdf;base64,' + btoa(binary);
|
|
||||||
}
|
|
||||||
|
|
||||||
browser.runtime.onMessage.addListener((msg, sender, sendResponse) => {
|
browser.runtime.onMessage.addListener((msg, sender, sendResponse) => {
|
||||||
if (msg && msg.type === 'generate-pdf') {
|
if (msg && msg.type === 'generate-pdf') {
|
||||||
generatePdf(msg.data)
|
generatePdf(msg.data)
|
||||||
@@ -53,9 +26,8 @@ function formatPeriod(period) {
|
|||||||
|
|
||||||
async function generatePdf(data) {
|
async function generatePdf(data) {
|
||||||
const bytes = await ISMIStools.buildStudyLoadPdf(data);
|
const bytes = await ISMIStools.buildStudyLoadPdf(data);
|
||||||
// Firefox accepts blob: object URLs; Chrome MV3 service worker has no
|
const blob = new Blob([bytes], { type: 'application/pdf' });
|
||||||
// URL.createObjectURL, so it falls back to a base64 data: URL there.
|
const url = URL.createObjectURL(blob);
|
||||||
const url = buildDownloadUrl(bytes);
|
|
||||||
const header = data.header || {};
|
const header = data.header || {};
|
||||||
const year = parseInt(data.year, 10);
|
const year = parseInt(data.year, 10);
|
||||||
const period = formatPeriod(data.period || header.semester || '');
|
const period = formatPeriod(data.period || header.semester || '');
|
||||||
@@ -77,10 +49,12 @@ async function generatePdf(data) {
|
|||||||
const onChanged = (delta) => {
|
const onChanged = (delta) => {
|
||||||
if (delta.id === id && delta.state && (delta.state.current === 'complete' || delta.state.current === 'interrupted')) {
|
if (delta.id === id && delta.state && (delta.state.current === 'complete' || delta.state.current === 'interrupted')) {
|
||||||
browser.downloads.onChanged.removeListener(onChanged);
|
browser.downloads.onChanged.removeListener(onChanged);
|
||||||
|
URL.revokeObjectURL(url);
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
browser.downloads.onChanged.addListener(onChanged);
|
browser.downloads.onChanged.addListener(onChanged);
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
|
URL.revokeObjectURL(url);
|
||||||
throw err;
|
throw err;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,11 +1,6 @@
|
|||||||
(function () {
|
(function () {
|
||||||
'use strict';
|
'use strict';
|
||||||
|
|
||||||
// Cross-browser API namespace (see background.js). No-op in Firefox.
|
|
||||||
if (typeof browser === 'undefined' || browser == null) {
|
|
||||||
var browser = (typeof chrome !== 'undefined' ? chrome : {});
|
|
||||||
}
|
|
||||||
|
|
||||||
const MASTER_KEY = 'enabled';
|
const MASTER_KEY = 'enabled';
|
||||||
|
|
||||||
async function isEnabled() {
|
async function isEnabled() {
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,145 @@
|
|||||||
|
# ISMIS Helper — Firefox Extension Design
|
||||||
|
|
||||||
|
**Date:** 2026-08-18
|
||||||
|
**Status:** Approved
|
||||||
|
**Target site:** `https://ismis.usc.edu.ph` (USC ISMIS student portal)
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
A personal Firefox extension (Manifest V3, no build step) that improves the USC ISMIS
|
||||||
|
student portal experience. It provides three features:
|
||||||
|
|
||||||
|
1. **Auto-login** — auto-fill and auto-submit the login form from a saved profile.
|
||||||
|
2. **Auto-accept Privacy Policy** — dismiss the recurring privacy-policy modal.
|
||||||
|
3. **Study Load PDF** — an on-page "Download PDF" button on the Study Load page that
|
||||||
|
generates a PDF replicating the official ISMIS Study Load document (Letter size,
|
||||||
|
with course descriptions looked up from the Offered Courses endpoint) and
|
||||||
|
downloads it directly.
|
||||||
|
|
||||||
|
A single **master toggle** disables all extension behavior on the portal.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
Single MV3 extension, plain JavaScript, no bundler. No background script — all logic
|
||||||
|
runs in the content script (scraping and print-document building happen in-page).
|
||||||
|
|
||||||
|
```
|
||||||
|
ismis-helper/
|
||||||
|
├── manifest.json # MV3 manifest, permissions, content script, popup, background
|
||||||
|
├── background.js # message handler: build PDF (pdf-lib) + download via downloads API
|
||||||
|
├── content.js # runs on ismis.usc.edu.ph: auto-login, privacy, button, scrape
|
||||||
|
├── parsers.js # UMD: table/profile/offered-courses parsing + filtering
|
||||||
|
├── pdf.js # UMD: buildStudyLoadPdf (Letter PDF, official layout, pagination)
|
||||||
|
├── popup.html # popup UI (master toggle + profiles)
|
||||||
|
├── popup.js # popup logic
|
||||||
|
├── popup.css # popup styles
|
||||||
|
├── libs/pdf-lib.min.js # vendored pdf-lib library (used by background)
|
||||||
|
└── icons/ # extension icons (16, 32, 48, 128)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Permissions (manifest.json)
|
||||||
|
- `storage` — persist profiles and the master toggle.
|
||||||
|
- `downloads` — save the generated Study Load PDF.
|
||||||
|
- `host_permissions` — `https://ismis.usc.edu.ph/*` for the content script.
|
||||||
|
- Background loads `libs/pdf-lib.min.js` + `pdf.js` via `background.scripts`.
|
||||||
|
|
||||||
|
## Background script
|
||||||
|
- `background.js` handles the `generate-pdf` message from the content script:
|
||||||
|
builds the PDF via `ISMIStools.buildStudyLoadPdf`, wraps the bytes in a Blob,
|
||||||
|
downloads via `browser.downloads.download({ saveAs: true })`, and revokes the
|
||||||
|
object URL when the download reaches `complete`/`interrupted` (and on failure).
|
||||||
|
|
||||||
|
## Component 1 — Auto-login
|
||||||
|
|
||||||
|
- Content script runs on `https://ismis.usc.edu.ph/Account/Login`.
|
||||||
|
- Reads the active (enabled) profile from `browser.storage.local`.
|
||||||
|
- Locates the username and password input fields (`name`/`id` = `Username` /
|
||||||
|
`Password`, with fallback variants).
|
||||||
|
- Fills both fields, then submits the form (auto-submit).
|
||||||
|
- If no profile is enabled, or the master toggle is off, does nothing.
|
||||||
|
|
||||||
|
## Component 2 — Auto-accept Privacy Policy
|
||||||
|
|
||||||
|
- On any portal page, if the privacy modal `#myModal` is present and visible:
|
||||||
|
- Check the `#Confirmation` checkbox ("I have read and understood the Privacy
|
||||||
|
Policy Statement").
|
||||||
|
- Click the `#Submit` button (Continue), which is disabled until the checkbox is
|
||||||
|
checked.
|
||||||
|
- Gated by the master toggle.
|
||||||
|
|
||||||
|
## Component 3 — Profiles
|
||||||
|
|
||||||
|
- Stored in `browser.storage.local` under key `profiles` as an array of:
|
||||||
|
`{ id, name, username, password, enabled }`.
|
||||||
|
- Popup provides add, edit, delete, and enable/disable per profile.
|
||||||
|
- Only one profile can be enabled at a time (enabling one disables the others);
|
||||||
|
that profile is used for auto-login.
|
||||||
|
- Master toggle stored under key `enabled` (boolean).
|
||||||
|
|
||||||
|
## Component 4 — Study Load PDF
|
||||||
|
|
||||||
|
### On-page button
|
||||||
|
- The content script watches the Study Load page (`#StudyLoad`). When the course
|
||||||
|
table appears (after the user selects academic period/year and searches), it
|
||||||
|
injects a **"Download PDF"** button inline with the
|
||||||
|
`12.00 Units / Total Units: 18.00` footer (button on the left, units text on the
|
||||||
|
right, via a flex row), styled like the page's buttons (`btn green`).
|
||||||
|
|
||||||
|
### Scrape
|
||||||
|
- Parse the course table (columns: Group #, Course Code, Schedule, Faculty, Units,
|
||||||
|
Status) via `parseStudyLoadTable`.
|
||||||
|
- **Header info** (full name, student ID, program, year level, semester) is scraped
|
||||||
|
from the **My Profile** page (`/Manage/Student`).
|
||||||
|
|
||||||
|
### Filtering
|
||||||
|
- **DISSOLVED courses are excluded** (`filterStudyLoadCourses`).
|
||||||
|
- Total units = sum of the included courses' units (`sumUnits`).
|
||||||
|
|
||||||
|
### Description lookup
|
||||||
|
- For each unique course code, POST to
|
||||||
|
`https://ismis.usc.edu.ph/CourseSchedule/CourseScheduleOffered` with the
|
||||||
|
`__RequestVerificationToken` and selected `AcademicPeriod`/`AcademicYear`, then
|
||||||
|
parse the returned table for the **Course Description**.
|
||||||
|
- If lookup fails for a course, the description is left blank and generation
|
||||||
|
continues.
|
||||||
|
|
||||||
|
### PDF generation
|
||||||
|
- `pdf.js` (`buildStudyLoadPdf`, using **pdf-lib**) builds a Letter-size (612×792pt)
|
||||||
|
PDF replicating the official layout: title block (STUDENT'S STUDY LOAD, semester,
|
||||||
|
date range, date enrolled), student info row (ID, name, program, year level), the
|
||||||
|
course table (GROUP, COURSE, COURSE DESCRIPTION, TEACHER, UNITS, NOTE — NOTE is
|
||||||
|
the status), and a footer (total units, "Printed by: …"). Multi-page
|
||||||
|
pagination re-draws the table header. NOTE column is wide enough for `REGULAR`.
|
||||||
|
- The content script sends the data to the background (`generate-pdf`), which
|
||||||
|
downloads the PDF via the `downloads` API (`saveAs: true`).
|
||||||
|
|
||||||
|
## Data flow
|
||||||
|
|
||||||
|
```
|
||||||
|
Study Load page ──▶ content script (scrape + filter DISSOLVED + description lookup)
|
||||||
|
│
|
||||||
|
▼ browser.runtime.sendMessage({ type: 'generate-pdf', data })
|
||||||
|
background.js (pdf-lib buildStudyLoadPdf)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
browser.downloads.download → Study Load PDF file
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error handling
|
||||||
|
|
||||||
|
- Master toggle off → no extension behavior on the portal.
|
||||||
|
- No enabled profile → no auto-login.
|
||||||
|
- Description lookup fails for a course → blank description, PDF still generated.
|
||||||
|
- No enrolled (non-DISSOLVED) courses → error toast, no download.
|
||||||
|
- Download fails → error toast; object URL is revoked.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- Node `node:test` suites: parsers (table/profile/offered-courses/filter/sum) and
|
||||||
|
pdf (valid Letter PDF output).
|
||||||
|
- Load via `about:debugging` → "Load Temporary Add-on".
|
||||||
|
- Verify auto-login on the login page.
|
||||||
|
- Verify privacy modal auto-accept.
|
||||||
|
- Verify profile add/edit/delete/toggle and master toggle.
|
||||||
|
- Verify the on-page Download PDF button: appears inline with the total-units
|
||||||
|
footer, excludes DISSOLVED courses, and downloads a Letter-size PDF.
|
||||||
+1
-1
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"manifest_version": 3,
|
"manifest_version": 3,
|
||||||
"name": "ISMIS Helper",
|
"name": "ISMIS Helper",
|
||||||
"version": "1.3.0",
|
"version": "1.2.0",
|
||||||
"description": "Auto-login, auto-accept privacy policy, and Study Load PDF for the USC ISMIS portal.",
|
"description": "Auto-login, auto-accept privacy policy, and Study Load PDF for the USC ISMIS portal.",
|
||||||
"permissions": ["storage", "downloads"],
|
"permissions": ["storage", "downloads"],
|
||||||
"host_permissions": ["https://ismis.usc.edu.ph/*"],
|
"host_permissions": ["https://ismis.usc.edu.ph/*"],
|
||||||
|
|||||||
+1
-2
@@ -4,8 +4,7 @@
|
|||||||
"private": true,
|
"private": true,
|
||||||
"description": "Firefox extension for the USC ISMIS portal",
|
"description": "Firefox extension for the USC ISMIS portal",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"test": "node --test",
|
"test": "node --test"
|
||||||
"build": "node scripts/build.js all"
|
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"pdf-lib": "^1.17.1"
|
"pdf-lib": "^1.17.1"
|
||||||
|
|||||||
@@ -1,10 +1,5 @@
|
|||||||
'use strict';
|
'use strict';
|
||||||
|
|
||||||
// Cross-browser API namespace (see background.js). No-op in Firefox.
|
|
||||||
if (typeof browser === 'undefined' || browser == null) {
|
|
||||||
var browser = (typeof chrome !== 'undefined' ? chrome : {});
|
|
||||||
}
|
|
||||||
|
|
||||||
const $ = (sel) => document.querySelector(sel);
|
const $ = (sel) => document.querySelector(sel);
|
||||||
|
|
||||||
const MASTER_KEY = 'enabled';
|
const MASTER_KEY = 'enabled';
|
||||||
|
|||||||
@@ -1,166 +0,0 @@
|
|||||||
'use strict';
|
|
||||||
// Zero-dependency build script: packages the extension for Firefox and Chrome.
|
|
||||||
// Usage: node scripts/build.js [firefox|chrome|all] [--version X.Y.Z]
|
|
||||||
const fs = require('fs');
|
|
||||||
const path = require('path');
|
|
||||||
|
|
||||||
const ROOT = path.join(__dirname, '..');
|
|
||||||
const DIST = path.join(ROOT, 'dist');
|
|
||||||
const FF_GECKO_ID = process.env.FF_GECKO_ID || 'ismis-helper@adrianbonpin';
|
|
||||||
|
|
||||||
// Order matters for the single-file Chrome service worker:
|
|
||||||
// fontkit -> pdf-lib -> pdf.js -> background.js
|
|
||||||
const CHROME_BG_PARTS = [
|
|
||||||
'libs/fontkit.min.js',
|
|
||||||
'libs/pdf-lib.min.js',
|
|
||||||
'pdf.js',
|
|
||||||
'background.js',
|
|
||||||
];
|
|
||||||
|
|
||||||
// Everything to copy from ROOT into a target, relative paths.
|
|
||||||
function collectFiles(srcDir, out = [], prefix = '') {
|
|
||||||
for (const entry of fs.readdirSync(srcDir)) {
|
|
||||||
const abs = path.join(srcDir, entry);
|
|
||||||
const rel = prefix ? prefix + '/' + entry : entry;
|
|
||||||
if (entry === '.git' || entry === 'node_modules' || entry === 'dist' ||
|
|
||||||
entry === 'docs' || entry === 'scripts' || entry === 'test' ||
|
|
||||||
entry === 'manifest.json' || entry.startsWith('.')) {
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
if (fs.statSync(abs).isDirectory()) collectFiles(abs, out, rel);
|
|
||||||
else out.push(rel);
|
|
||||||
}
|
|
||||||
return out;
|
|
||||||
}
|
|
||||||
|
|
||||||
function copyDir(relList, destDir) {
|
|
||||||
for (const rel of relList) {
|
|
||||||
const src = path.join(ROOT, rel);
|
|
||||||
const dst = path.join(destDir, rel);
|
|
||||||
fs.mkdirSync(path.dirname(dst), { recursive: true });
|
|
||||||
fs.copyFileSync(src, dst);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function readManifest() {
|
|
||||||
return JSON.parse(fs.readFileSync(path.join(ROOT, 'manifest.json'), 'utf8'));
|
|
||||||
}
|
|
||||||
|
|
||||||
// ---- STORED zip writer (no compression, valid for both browsers) ----
|
|
||||||
function crc32(buf) {
|
|
||||||
let table = [];
|
|
||||||
for (let n = 0; n < 256; n++) {
|
|
||||||
let c = n;
|
|
||||||
for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
|
|
||||||
table[n] = c >>> 0;
|
|
||||||
}
|
|
||||||
let crc = 0xffffffff;
|
|
||||||
for (let i = 0; i < buf.length; i++) crc = table[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
|
|
||||||
return (crc ^ 0xffffffff) >>> 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
function writeStoredZip(files, baseDir, zipPath) {
|
|
||||||
const chunks = [];
|
|
||||||
const central = [];
|
|
||||||
let offset = 0;
|
|
||||||
for (const rel of files) {
|
|
||||||
const data = fs.readFileSync(path.join(baseDir, rel));
|
|
||||||
const name = Buffer.from(rel, 'utf8');
|
|
||||||
const crc = crc32(data);
|
|
||||||
const lh = Buffer.alloc(30);
|
|
||||||
lh.writeUInt32LE(0x04034b50, 0);
|
|
||||||
lh.writeUInt16LE(20, 4);
|
|
||||||
lh.writeUInt16LE(0, 6);
|
|
||||||
lh.writeUInt16LE(0, 8); // method: stored
|
|
||||||
lh.writeUInt16LE(0, 10);
|
|
||||||
lh.writeUInt16LE(0, 12);
|
|
||||||
lh.writeUInt32LE(crc, 14);
|
|
||||||
lh.writeUInt32LE(data.length, 18);
|
|
||||||
lh.writeUInt32LE(data.length, 22);
|
|
||||||
lh.writeUInt16LE(name.length, 26);
|
|
||||||
lh.writeUInt16LE(0, 28);
|
|
||||||
chunks.push(lh, name, data);
|
|
||||||
const ch = Buffer.alloc(46);
|
|
||||||
ch.writeUInt32LE(0x02014b50, 0);
|
|
||||||
ch.writeUInt16LE(20, 4);
|
|
||||||
ch.writeUInt16LE(20, 6);
|
|
||||||
ch.writeUInt16LE(0, 8);
|
|
||||||
ch.writeUInt16LE(0, 10);
|
|
||||||
ch.writeUInt16LE(0, 12);
|
|
||||||
ch.writeUInt32LE(crc, 16);
|
|
||||||
ch.writeUInt32LE(data.length, 20);
|
|
||||||
ch.writeUInt32LE(data.length, 24);
|
|
||||||
ch.writeUInt16LE(name.length, 28);
|
|
||||||
ch.writeUInt16LE(0, 30);
|
|
||||||
ch.writeUInt16LE(0, 32);
|
|
||||||
ch.writeUInt16LE(0, 34);
|
|
||||||
ch.writeUInt16LE(0, 36);
|
|
||||||
ch.writeUInt32LE(0, 38);
|
|
||||||
ch.writeUInt32LE(offset, 42);
|
|
||||||
central.push(ch, name);
|
|
||||||
offset += lh.length + name.length + data.length;
|
|
||||||
}
|
|
||||||
const cdStart = offset;
|
|
||||||
let cdSize = 0;
|
|
||||||
central.forEach((b) => { cdSize += b.length; });
|
|
||||||
const eocd = Buffer.alloc(22);
|
|
||||||
eocd.writeUInt32LE(0x06054b50, 0);
|
|
||||||
eocd.writeUInt16LE(files.length, 8);
|
|
||||||
eocd.writeUInt16LE(files.length, 10);
|
|
||||||
eocd.writeUInt32LE(cdSize, 12);
|
|
||||||
eocd.writeUInt32LE(cdStart, 16);
|
|
||||||
eocd.writeUInt16LE(0, 20);
|
|
||||||
const all = Buffer.concat([...chunks, ...central, eocd]);
|
|
||||||
fs.writeFileSync(zipPath, all);
|
|
||||||
}
|
|
||||||
|
|
||||||
function buildTarget(target, version) {
|
|
||||||
const dir = path.join(DIST, target);
|
|
||||||
fs.rmSync(dir, { recursive: true, force: true });
|
|
||||||
fs.mkdirSync(dir, { recursive: true });
|
|
||||||
|
|
||||||
const relList = collectFiles(ROOT);
|
|
||||||
copyDir(relList, dir);
|
|
||||||
|
|
||||||
if (target === 'firefox') {
|
|
||||||
const m = readManifest();
|
|
||||||
if (version) m.version = version;
|
|
||||||
m.browser_specific_settings = { gecko: { id: FF_GECKO_ID } };
|
|
||||||
fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(m, null, 2) + '\n');
|
|
||||||
} else { // chrome
|
|
||||||
const m = readManifest();
|
|
||||||
if (version) m.version = version;
|
|
||||||
delete m.background;
|
|
||||||
m.background = { service_worker: 'background.chrome.js' };
|
|
||||||
delete m.browser_specific_settings;
|
|
||||||
fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(m, null, 2) + '\n');
|
|
||||||
const worker = CHROME_BG_PARTS
|
|
||||||
.map((p) => fs.readFileSync(path.join(ROOT, p), 'utf8'))
|
|
||||||
.join('\n;\n');
|
|
||||||
fs.writeFileSync(path.join(dir, 'background.chrome.js'), worker);
|
|
||||||
}
|
|
||||||
|
|
||||||
const suffix = version ? '-' + version : '';
|
|
||||||
const zipName = path.join(DIST, `ismis-helper-${target}${suffix}.zip`);
|
|
||||||
writeStoredZip(collectFiles(dir), dir, zipName);
|
|
||||||
console.log(`built ${target}: ${zipName}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
function main() {
|
|
||||||
const args = process.argv.slice(2);
|
|
||||||
const rawTargets = args.filter((a) => !a.startsWith('--'));
|
|
||||||
const vi = args.indexOf('--version');
|
|
||||||
let version = null;
|
|
||||||
if (vi !== -1 && args[vi + 1]) version = String(args[vi + 1]).replace(/^v/, '');
|
|
||||||
const requested = rawTargets.length ? rawTargets : ['all'];
|
|
||||||
const targets = requested.includes('all')
|
|
||||||
? ['firefox', 'chrome']
|
|
||||||
: requested.filter((t) => t === 'firefox' || t === 'chrome');
|
|
||||||
if (!targets.length) {
|
|
||||||
console.error('Usage: node scripts/build.js [firefox|chrome|all] [--version X.Y.Z]');
|
|
||||||
process.exit(1);
|
|
||||||
}
|
|
||||||
for (const t of targets) buildTarget(t, version);
|
|
||||||
}
|
|
||||||
|
|
||||||
main();
|
|
||||||
+1
-18
@@ -38,19 +38,7 @@ function extractPdfText(bytes) {
|
|||||||
return execFileSync('python3', ['-c', script], { encoding: 'utf8' });
|
return execFileSync('python3', ['-c', script], { encoding: 'utf8' });
|
||||||
}
|
}
|
||||||
|
|
||||||
// PyMuPDF (fitz) is only needed for the text-extraction assertions below. It is
|
test('buildStudyLoadPdf returns valid PDF bytes', async () => {
|
||||||
// installed in CI, but if it is missing locally we skip those assertions rather
|
|
||||||
// than hard-failing.
|
|
||||||
function fitzAvailable() {
|
|
||||||
try {
|
|
||||||
execFileSync('python3', ['-c', 'import fitz'], { stdio: 'ignore' });
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
test('buildStudyLoadPdf returns valid PDF bytes', async (t) => {
|
|
||||||
const bytes = await buildStudyLoadPdf(sampleData);
|
const bytes = await buildStudyLoadPdf(sampleData);
|
||||||
assert.ok(bytes instanceof Uint8Array);
|
assert.ok(bytes instanceof Uint8Array);
|
||||||
const head = Buffer.from(bytes.slice(0, 5)).toString('latin1');
|
const head = Buffer.from(bytes.slice(0, 5)).toString('latin1');
|
||||||
@@ -58,11 +46,6 @@ test('buildStudyLoadPdf returns valid PDF bytes', async (t) => {
|
|||||||
const doc = await PDFLib.PDFDocument.load(bytes);
|
const doc = await PDFLib.PDFDocument.load(bytes);
|
||||||
assert.strictEqual(doc.getPageCount(), 1);
|
assert.strictEqual(doc.getPageCount(), 1);
|
||||||
|
|
||||||
if (!fitzAvailable()) {
|
|
||||||
t.skip('PyMuPDF (fitz) not available; skipping PDF text assertions');
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
const text = extractPdfText(bytes);
|
const text = extractPdfText(bytes);
|
||||||
assert.ok(text.includes('CIS 2101'), 'PDF text should contain course code CIS 2101');
|
assert.ok(text.includes('CIS 2101'), 'PDF text should contain course code CIS 2101');
|
||||||
assert.ok(text.includes("STUDENT'S STUDY LOAD"), 'PDF text should contain the title');
|
assert.ok(text.includes("STUDENT'S STUDY LOAD"), 'PDF text should contain the title');
|
||||||
|
|||||||
Reference in New Issue
Block a user