PageLamp v0.3.0-alpha.1

This is the first pre-release of PageLamp v0.3. It is for people who want to try it and tell us
what goes wrong. It isn't finished and it can have bugs. If you'd rather wait, stay on v0.1.0,
the latest stable release: https://github.com/Euswbnix/pagelamp/releases/tag/v0.1.0

The README has the setup: https://github.com/Euswbnix/pagelamp#readme
The CHANGELOG has every change: https://github.com/Euswbnix/pagelamp/blob/main/CHANGELOG.md

Read this first

• Your data moves to a new format that v0.1.0 can't open. A copy of the old database is kept.
  See "Your data after the upgrade" and "Going back to v0.1.0" below.
• PageLamp now syncs by itself while it is open. You can turn that off.
• It reads more of a Canvas course than v0.1.0 did, and Canvas may record that. See "What
  PageLamp reads from Canvas" below.
• It looks for a new version on GitHub once a day. You can turn that off.
• PageLamp still calls no AI model itself. Your own AI app reads your courses, as before.
• The native macOS app in the repository (apps/macos) is not part of this release. The macOS
  download is the same desktop app as on Windows and Linux.

What's new since v0.1.0

• Automatic sync. While PageLamp is open it syncs by itself: twice a day, unless you choose once
  a day or off under "Sources & sync" (command line: pagelamp sync --auto off). With nobody at
  the app it checks your token and asks Canvas only for your course list, deadlines and
  announcements. When you open PageLamp, or come back to its window and click or type (scrolling doesn't count),
  and the last full sync is old enough or a newly found course hasn't been read yet, it runs a
  full sync, the same as pressing Sync. It never downloads Canvas files by itself, nothing syncs
  while PageLamp is closed, and after you stop a sync nothing starts by itself for an hour.
• PageLamp looks for updates. See "Updates from this version on" below.
• Weeks that follow the real class dates. A Canvas term that is much longer than the classes
  is no longer used to count weeks. Each course shows its week, "Exams", "Ended" or when it
  starts, and its Timeline tab lists the dates PageLamp used, the ones it didn't, and why. Still
  wrong? Set the first and last day of classes under "Course dates" on that tab. A course that
  is over, inactive or hasn't started shows no current week.
• Past courses. Courses that have ended, or that have no dates and nothing new for months, move
  to a collapsed "Past courses" group; their deadlines stay listed. "I'm still taking this"
  moves one back.
• More of a Canvas course, and a list of what wasn't read. PageLamp now reads a course's Home
  page and the pages its texts link to. A Canvas course's page lists what PageLamp didn't read
  and why ("What PageLamp didn't read", at the end of "This week").
• Stop a sync. "Stop" ends a sync after the file it is on; what was synced so far is kept.
• Sturdier file reading. Each file is read in a separate process with time and memory limits,
  so one bad PDF can't stop a sync, and a file whose text can't be read says why.
• Cleaner link addresses. A link address in a Canvas page can carry a parameter that opens a
  file for whoever has the address. PageLamp now removes such parameters from the link
  addresses in the text it stores, and before it gives text to your AI app.
• For your AI app. A new read-only tool, list_materials, lists every material of a course.
  sync_status says whether PageLamp syncs by itself and how old each source's data is. Your AI
  app is told what PageLamp didn't read, and that it can't start a sync and must not try.
• A new look for the desktop app, with "Reduce transparency" under Settings, Appearance.
• Command line. pagelamp courses groups courses into Current, Upcoming and Past (past ones with
  --past or --all). New: pagelamp course timeline, pagelamp course keep, and pagelamp sync
  --auto with off, daily or twice-daily.

What PageLamp reads from Canvas, and what Canvas may record

Canvas may record a sync like any other access to a course. As far as we know, the course's
access report, which instructors can see, may list the areas PageLamp reads (modules, pages,
assignments, files, announcements) and the pages it reads, and a sync may refresh the "Last
Activity" time shown for you in the course. We can't see Canvas's records, so we can't say
exactly what it keeps. On the one real account we checked, each full sync moved that "Last
Activity" time to the time of the sync in every course, and the lighter requests described
below moved none. With automatic sync on, a full sync can run without you pressing Sync,
when you are at the app: when the last full sync is 12 hours old (24 with "Once a day"), or
sooner when PageLamp has found a new course it hasn't read yet. It then reads every course of
that source, not only the new one.

Compared with v0.1.0, a full sync of a Canvas course now:

• also reads the page the course's Home shows, and the pages of the same course that the Home
  page, the syllabus, other pages and announcements link to. One step only, and at most 40
  linked pages and 150 linked files per course in one sync. Linked files are listed, not
  downloaded.
• asks for the announcements of the last 365 days (v0.1.0: 120).
• no longer reads a page that a module asks you to view, until you have viewed it in Canvas. As
  far as we can tell, reading it for you could mark it as viewed. In two cases PageLamp can't
  know beforehand: the first time it reads a course's Home page, and when a link uses another
  address of such a page. If it opened one, the sync says so, and it doesn't read that page
  again until you have viewed it. v0.1.0 read every page of a module.
• reads some pages again. A page Canvas lists with a change date is read only when it is new or
  has changed. A page with no change date (in a course that doesn't show its Pages list: the
  Home page, the pages of its modules and linked pages) is read again each time you press Sync,
  and by an automatic sync at most once a day. Once after this update, an unchanged page is read
  again in a course that doesn't show its Files list, to find the files it links to.

PageLamp only reads: GET requests with your own token. It never asks for a course's Pages list
or Files list when the course's menu doesn't show it. A full sync asks for each course's modules
and assignments, and every sync for its announcements, whatever the menu shows. Assignments and
quizzes stay title, due date and link. Files are downloaded only when you ask.

With nobody at the app, an automatic sync makes no request for a course's modules, pages, file
list or assignments. Canvas keeps its own records, and we can't promise that these lighter
requests leave none. To sync only when you press Sync, set automatic sync to "Off".

What PageLamp didn't read is listed with a reason on the course's page and for your AI app.
After a sync, the source's row and pagelamp sync say how many things weren't read in each
course.

Downloads

• Desktop app (it includes the pagelamp command your AI app needs):
  macOS: PageLamp_0.3.0_universal.dmg, one file for Apple silicon and Intel.
  Windows (x86_64): PageLamp_0.3.0_x64-setup.exe. It installs for your account only; there is
  no .msi any more.
  Linux (x86_64): the .deb or the .rpm (they also install /usr/bin/pagelamp), or
  PageLamp_0.3.0_amd64.AppImage, which runs the app, but your AI app can't use the pagelamp
  inside it.
• Command line only: pagelamp-v0.3.0-alpha.1-aarch64-apple-darwin.tar.gz (Apple silicon Mac),
  pagelamp-v0.3.0-alpha.1-x86_64-apple-darwin.tar.gz (Intel Mac),
  pagelamp-v0.3.0-alpha.1-x86_64-unknown-linux-gnu.tar.gz (Linux) or
  pagelamp-v0.3.0-alpha.1-x86_64-pc-windows-msvc.zip (Windows). Each holds pagelamp
  (pagelamp.exe in the .zip), LICENSE, THIRD-PARTY-NOTICES.txt and README.md.
• Installer names say 0.3.0, and so do the .deb and .rpm package versions. The app says
  0.3.0-alpha.1 (Settings, About, or pagelamp --version).
• The .app.tar.gz, .sig and latest.json files are for the updater; you don't need them.
• Checksums: SHA256SUMS lists every installer, archive and updater file. Check with
  shasum -a 256 -c SHA256SUMS --ignore-missing
  Each of those files also has a GitHub build attestation; how to check one is in
  https://github.com/Euswbnix/pagelamp/blob/main/SECURITY.md

Installing (also over v0.1.0)

v0.1.0 doesn't update itself and won't offer this version, so install it by hand. Quit PageLamp
and your AI app first.

• macOS: open the .dmg, drag PageLamp into Applications (choose "Replace" if v0.1.0 is there)
  and open it from there. The app, the .dmg and the command-line pagelamp are signed with a
  Developer ID and notarized by Apple; macOS asks once whether to open an app downloaded from
  the internet. Be online for that first run.
• Windows: run the -setup.exe. The installer, the app and pagelamp.exe are signed, so Windows
  shows a verified publisher; SmartScreen may still warn while this release is new: "More
  info", then "Run anyway".
• Windows, if you installed v0.1.0 from the .msi: the new installer is made to remove that
  installation first, and Windows may ask for an administrator's permission for it. Afterwards
  pagelamp.exe is in another folder, so copy the setup from "Connect your AI app" into your AI
  app again. We haven't walked through this path by hand; please tell us how it went.
• Linux: install the .deb or the .rpm, or make the .AppImage executable and run it. Builds are
  not code-signed; check them against SHA256SUMS. Saving a calendar-feed link or a Canvas token
  needs GNOME Keyring or KWallet.
• If your AI app runs a pagelamp you installed on its own (from an archive, or with cargo):
  replace that file with this version's too. Once your data is in the new format, v0.1.0's
  pagelamp can't read it and asks you to update PageLamp at every call.

Your data after the upgrade

• The first time this version opens your data (the...

PageLamp v0.1.0

First release of PageLamp — a local course knowledge base for the AI app you already use.
See the README for setup and the
CHANGELOG for what's included.

Downloads

• Desktop app (includes the pagelamp command your AI app needs): .dmg for macOS
  (aarch64 = Apple silicon, x64 = Intel), .msi / -setup.exe for Windows,
  .deb / .rpm for Linux (they also install /usr/bin/pagelamp). The .AppImage runs the app,
  but your AI app can't use the pagelamp inside it in this release.
• Command-line only: pagelamp-v0.1.0-<platform>.tar.gz (aarch64-apple-darwin =
  Apple silicon Mac, x86_64-apple-darwin = Intel Mac, x86_64-unknown-linux-gnu = Linux) or
  …-x86_64-pc-windows-msvc.zip (Windows); each contains pagelamp, LICENSE and README.md.
• Checksums: SHA256SUMS covers every file — verify with shasum -a 256 -c SHA256SUMS --ignore-missing.

First launch

• macOS: the app, the .dmg and the command-line pagelamp are signed with a Developer ID and
  notarized by Apple. Drag PageLamp from the .dmg into Applications and open it from there;
  macOS asks once whether to open an app downloaded from the internet. Be online for that first run.
• Windows: the installers, the app and pagelamp.exe are signed, so Windows shows a verified
  publisher. SmartScreen may still warn while this new release builds up reputation:
  More info → Run anyway.
• Linux: builds are not code-signed; check them against SHA256SUMS. Saving a calendar-feed link
  or Canvas token needs GNOME Keyring or KWallet.

Known issues

• Wrong week (for example "Week 22" in September): Canvas can report a term much wider than the
  classes (the University of Toronto's Fall term runs from May to January). Set the real dates in the
  course's Timeline tab (Wrong week? Set this course's term dates).
• Old courses keep syncing: when an instructor never closed a past course in Canvas, it still
  appears. Hide it (course → Settings → Hide this course); it stays hidden and your AI app never
  sees it.
• Both are fixed properly in v0.3, which reads the syllabus and schedule to work out each course's
  week and lets you remove finished courses.
• Link addresses with an access parameter: a link in a Canvas page can carry a parameter (such
  as verifier=) that opens a course file for whoever has the address. v0.1.0 keeps such addresses
  in the text it stores and can pass them to your AI app. The pre-release
  v0.3.0-alpha.1 removes these
  parameters from the text it stores (also from what v0.1.0 stored) and from what it gives your AI app.

Updating later

v0.1.0 doesn't update itself yet (automatic updates arrive in v0.3). After installing a newer
build, quit your AI app completely and open it again so it starts the new pagelamp.

Please tell us

What worked, what didn't, and which week your courses are in vs. what PageLamp says —
open an issue and add a diagnostic
report (Settings → Help & feedback → Copy diagnostic report…, or pagelamp report). Read it
first; never paste tokens, calendar links or course materials.