adrianbonpin
9cc4fa5c97
build-extension / build (push) Successful in 37s
Squash merge of feat/ismis-helper into prod.
87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
# 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.
|