@ivanbard/dd2l 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ivanbard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dd2l
+
+i am not the biggest fan of D2L Brightspace, and sometimes wish i could get what im looking for without digging through 14 menus that differ from course to course. to solve that i made dd2l, a dynamic companion app to D2L Brightspace that does what you need, and adapts to your needs with time.
+
+dd2l is a local student companion for Queen's onQ. Sync your courses, search
+your materials, and ask questions with sources.
+
+## How it works
+
+- sign in to onQ through Chrome, including your school's MFA
+- collect course materials, assignments, grades, announcements and syllabus text
+- search the local cache, browse sources, and customize your home screen widgets
+- connect ChatGPT to compose adaptive workspaces around your goals
+
+Connect ChatGPT in Settings to use your existing plan, then describe what you
+want to do: **“Help me get ready for tomorrow's seminar”**, **“What should I
+prioritize across my classes?”**, or **“I'm stuck on the filter design report.”**
+The connected model interprets the goal, selects relevant records across
+courses, and generates an interactive workspace: a planner, practice session,
+rubric explorer, calculator, or another layout suited to the task. There is no required prompt format or fixed set of
+supported task names. If it needs clarification, answer in the same composer.
+
+Follow-ups carry the workspace's goal, generated interface and local progress, so
+you can change the layout while retaining notes and checked items. Use **Sources**
+to inspect verified coursework, or **Restart progress** to reset the current canvas. A connected model is selected by default;
+requests run only when you send a prompt, with the sharing notice visible.
+Choose **Local search** for keyword search and deterministic assignment views
+without sending data to AI. New search clears the goal; changing course clears
+context and sets a hard scope for the next request.
+
+The model can discover course areas, read uncached documents, and follow supported
+document links through the connector before composing the workspace. Retrieved
+materials enter the same cache used by search and sync. This covers accessible
+course content, assignment instructions/rubrics/attachments, your submission or
+quiz history, discussions, grades, announcements and calendar information.
+
+Adaptive requests use planning followed by interface generation from selected
+excerpts. Live research adds planning turns, bounded to four read rounds and eight
+connector operations per request. Generated HTML/CSS
+renders inside an isolated frame; JavaScript runs in a network-blocked worker
+through a small state/event interface. No frontend framework or external
+inference service is required. Local progress lasts for the current visit. Missing, inaccessible,
+and stale records remain explicit. Cached submissions do not confirm current
+submission status, and generated guidance should be checked against its sources.
+
+The connector is read-only. It does not submit work or change grades, posts,
+quiz attempts or completion states. Coverage depends on what onQ makes accessible.
+Live research uses approved API and document readers; it cannot click through
+arbitrary pages or sign into private external course tools.
+
+## School not listed?
+Choose **My school isn't listed** during setup and paste your school's
+Brightspace address; `https://` is added if omitted. dd2l uses that site for sign-in, syncing, and source links, and
+remembers it for later launches. Other schools have not been verified; their
+authentication or API access may differ. You can also [report a missing school](https://github.com/ivanbard/dd2l/issues/new?template=missing-url.yml)
+using the guided issue form. Include your school's name and Brightspace URL if
+known to help add official support.
+Stop dd2l and run `dd2l logout` before switching schools; this deletes its saved
+school session and coursework cache.
+
+## Run
+
+Requires Windows, Node.js 24 or newer, and Google Chrome. This repository includes
+an npm CLI; the commands below work once the package is published to npm:
+
+```powershell
+npx @ivanbard/dd2l setup
+```
+
+Setup explains local storage, asks before connecting onQ, opens Chrome for school
+sign-in and MFA, then opens the app and starts collecting coursework. Keep that
+one terminal open; Ctrl+C stops both the app and sync. The initial view may be
+empty while collection runs. Collection advances through up to five courses per
+pass every 15 minutes, so the first pass is not a complete download.
+
+Next time, run `npx @ivanbard/dd2l start`. If the school session expires, stop the app and
+run `npx @ivanbard/dd2l setup` again. Optional ChatGPT sign-in is in Settings.
+
+Alternatively, install globally with `npm install -g @ivanbard/dd2l`, then use `dd2l setup`
+and `dd2l start`. Installation itself does not open browsers or connect accounts;
+setup runs explicitly in an interactive terminal.
+
+To run the current source checkout before publication:
+
+```powershell
+npm ci
+npm run setup
+```
+
+On later launches use `npm start -- start`. The individual `login`, `audit`,
+`sync`, and `npm run ui` commands remain available for manual operation.
+
+Or try fictional data without a school login:
+
+```powershell
+npm run ui -- --demo
+```
+
+## Your data
+
+School sessions stay on your computer, encrypted with Windows DPAPI. The course
+cache lives in `%LOCALAPPDATA%\dd2l` and is **not encrypted**. Local search does
+not send your question to an AI provider.
+
+For AI answers, connect ChatGPT in Settings and choose a model below the prompt.
+Submitting sends your goal, previous workspace context, course previews and selected excerpts to OpenAI and uses
+your plan's limits. Check generated answers against the supplied sources.
+
+Stop the app, then run `dd2l logout` (or `npm start -- logout` from source) to
+remove the saved school session and inventory. Disconnect
+ChatGPT separately in Settings; clear the site's browser data to remove saved
+widget preferences and shortcut titles.
+
+More docs are in [`docs/`](docs/README.md), including commands, ChatGPT setup,
+collection limits and cache behavior.
+
+Run `npm test` for tests and `npm run ui:check` for browser checks.
+Third-party attribution is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+Original dd2l code is [MIT licensed](LICENSE); third-party assets retain their
+own licenses. Maintainers: see [PUBLISHING.md](https://github.com/ivanbard/dd2l/blob/main/PUBLISHING.md)
+for release setup.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,50 @@
+# UI icons
+
+The four sidebar action icons are from [Lucide](https://lucide.dev), version 0.468.0 (square-pen, search, book-open, settings), with their stroke color set to match the UI. The upstream ISC license notice is retained in [ui/assets/LUCIDE-LICENSE.txt](ui/assets/LUCIDE-LICENSE.txt). The SVGs are bundled locally; no icon runtime or external requests are required.
+
+# Dot-matrix loading indicator
+
+The app's 5×5 Origin Wave indicator is adapted from `DotmSquare12` (`@dotmatrix/dotm-square-12`), dot-matrix v1.5.0 by [zzzzshawn/matrix](https://github.com/zzzzshawn/matrix), as published at [Dot Matrix](https://dotmatrix.zzzzshawn.cloud/). `ui/loading.js` and the `dot-origin-wave` CSS preserve its origin, Manhattan ring delays, opacity curve and reduced-motion appearance in plain JavaScript/CSS. This adaptation is bundled for use inside dd2l, not offered as a standalone component or library. No React, Tailwind, registry CLI or external runtime is bundled.
+
+The upstream license is retained below:
+
+Custom Proprietary License
+
+Copyright (c) 2026 dot-matrix contributors
+All rights reserved.
+
+Permission is granted to use this software, including in commercial and non-commercial products.
+
+The following are strictly prohibited without prior written permission from the copyright holder:
+1. Publishing, distributing, or presenting any component from this project as a standalone reusable component, or claiming it as part of another component library or similar reusable component collection.
+2. Selling, sublicensing, renting, leasing, or otherwise commercializing any component from this project, whether modified or unmodified, as a standalone component offering.
+
+Any use not expressly permitted by this license is prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# Reference implementation
+
+Authentication behavior and endpoint discovery were informed by [brightspace-mcp-server](https://github.com/RohanMuppa/brightspace-mcp-server), version 5.1.27, by Rohan Muppa. dd2l does not import or run that server. The applicable notice is retained here for attribution of the reference work:
+
+MIT License
+
+Copyright (c) 2026 Rohan Muppa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/dd2l.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+if (Number(process.versions.node.split('.')[0]) < 24) {
+  console.error('dd2l requires Node.js 24 or newer. Install it from https://nodejs.org, then retry.');
+  process.exitCode = 1;
+} else {
+  await import('../src/cli.mjs');
+}

package/docs/README.md

@@ -0,0 +1,227 @@
+# dd2l guide
+
+A direct, read-only Brightspace connector for a customizable, promptable student companion. The first target is one Queen's onQ account on Windows.
+
+The connector signs in using your installed Google Chrome browser, reuses a protected school session, inventories course data, and can refresh a selected course or rotate through all accessible courses. It runs directly against Brightspace; no MCP server or model provider is involved.
+
+## Run
+
+Setup lists Queen's onQ and lets you enter another school's HTTPS Brightspace
+URL. The `https://` prefix is optional and added automatically. Pasted course URLs are reduced to their site origin; credentials embedded
+in a URL are rejected. The selected site is saved after successful sign-in and
+reused by subsequent connector commands and cached source links. Existing
+Queen's installations keep working without setup changes. Other schools remain
+unverified; use the issue link shown during setup to request official support.
+Stop the worker and run `logout` before switching accounts or schools.
+
+The guided source-checkout path is `npm ci`, then `npm run setup`. Setup asks
+before connecting onQ, completes school sign-in, opens the UI, and runs sync in
+the same terminal. Use `npm start -- start` on later launches. Keep the terminal
+open; Ctrl+C stops both. If sign-in expires, rerun setup. Collection remains
+incremental, with the same batching and 15-minute cadence described below.
+
+The npm package exposes `dd2l setup` and `dd2l start` (or `npx @ivanbard/dd2l setup` and
+`npx @ivanbard/dd2l start` without a global install) once published. It has no interactive
+install hook. The repository has not been published by this setup change.
+
+For manual operation:
+
+Requires Windows, Node.js 24 or newer, and Google Chrome. From this directory:
+
+```powershell
+npm ci
+npm run login
+npm start -- courses
+npm run audit
+npm start -- syllabus
+npm run status
+```
+
+Complete school sign-in and MFA in Chrome when requested. No school password is collected or saved. The default audit prefers the most recently accessed active, accessible course, falling back to another accessible enrollment if necessary. To select a particular course, use its ID from `courses`:
+
+```powershell
+npm run audit -- --course COURSE_ID --from 2026-09-01T00:00:00Z --to 2027-01-01T00:00:00Z
+npm run sync -- --course COURSE_ID
+npm start -- syllabus --course COURSE_ID
+npm run audit -- --all
+npm run sync -- --all
+```
+
+Replace `COURSE_ID` with the numeric ID. `sync` keeps running in the terminal until Ctrl+C; shutdown waits for the current bounded audit to finish. Without `--course`, sync reuses the last selected course and pins that choice for subsequent polls. Keep the computer and terminal running. If the school session expires, the worker stops with `needs_login`; run `login`, then restart `sync`. Temporary failures back off, and server retry guidance is respected. Concurrent mutating commands are prevented by a process lock; `status` can inspect a running worker.
+
+`--all` rotates through up to five accessible course offerings per pass, including historical courses still accessible to this account. It preserves the pinned single-course selection. Each course's assignment, document and discussion cursors are saved after its audit commits; another pass resumes the remaining objects. Sync waits 15 minutes between passes, so a full sweep can take multiple polling intervals. A rate-limit response stops further reads in that pass and honors the server's retry delay.
+
+For a sustained foreground check, run `npm run soak -- --minutes 180`. This uses the real sync cadence, writes structural results to the ignored `.dd2l/soak-summary.json`, and stops after the observation window and any in-progress audit finish. It does not force session expiry or bypass MFA. A one-minute smoke run has passed; a multi-hour run remains to be performed.
+
+Run `npm start -- --help` for commands and `npm test` for the focused checks.
+
+## UI prototype
+
+```powershell
+npm run ui
+```
+
+Open the printed [local URL](http://127.0.0.1:4173). The home screen implements the [Figma Home design](https://www.figma.com/design/ASr0dnwupPLbXmeT1AiPGg/dd2l?node-id=1-3): prompt, course selector, sidebar and profile. Search finds keyword matches in cached course materials and displays source excerpts with retrieval dates and stale-cache labels. Courses opens a material browser; Settings and Profile show connection status and refresh instructions. The source link opens the course in onQ using your normal browser sign-in.
+
+Local search reads the existing inventory without changing it or loading school credentials. Run `npm run audit -- --all` or keep `npm run sync -- --all` running separately to collect data. Each search reads the current cache. Only courses confirmed accessible in cached enrollments are shown; unavailable material stays unavailable, and coverage is limited to what the connector has collected. The mode dropdown uses an available ChatGPT model when connected, or **Local search** otherwise. Local search matches keywords; submitting with a connected model builds a workspace around your goal.
+
+The homescreen includes upcoming deadlines, recent class announcements, and shortcuts to classes or cached materials. **Customize** enables a four-column, eight-row grid: drag a widget to move it live, or drag any edge or corner to resize it. A cell preview marks the proposed placement; overlapping or out-of-bounds drops return to the original position. Escape cancels the gesture. Focus a widget and use arrow keys to move or Shift + arrows to resize without a pointer. Remove widgets or add them back with **Add widget**. Narrow screens stack widgets normally and show a horizontally scrollable grid while customizing. **Pin shortcut** opens a searchable class/material picker; selecting a shortcut browses its cached sources. New search returns to the homescreen.
+
+Waiting states use the Dot Matrix Square 12 / Origin Wave indicator: search and AI requests, course/model loading, widget refreshes, panels and account actions. Its 5×5 ripple is adapted to plain JavaScript/CSS, bundled locally and static when reduced motion is preferred. Loading states clear after success, failure or cancellation; concurrent loads share an indicator until all finish. Attribution and the upstream usage license are in [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md).
+
+Layouts and up to 20 shortcut references save in browser local storage, separately for each school account and demo mode. They do not sync across browsers or ports. Shortcut references include course-material titles and remain after CLI logout; clear this site's browser data to remove saved preferences. Inaccessible material is not rendered even if its reference remains pinned. **Refresh cache view** rereads the local inventory, without running a school sync. Deadlines require explicit due dates, announcements use publication dates when available, and stale cache entries remain labeled; an empty widget does not establish that onQ has no updates.
+
+### Use your ChatGPT plan
+
+In the live UI, open Settings or Profile and choose **Continue with ChatGPT**.
+Complete registration and plan-use consent on OpenAI's website, then return to
+dd2l. No API key is needed. An available connected model is selected by default;
+the sharing notice identifies AI mode. Sending a prompt starts a request;
+loading the app, typing and changing models never send coursework. Choose
+**Local search** for local keyword retrieval and assignment views. New search
+clears workspace context and restores the connected model default.
+
+Adaptive mode has no assignment-specific prompt gate or fixed intent list.
+The first model call receives the request, prior workspace goal and selected
+source references, accessible course names, and up to 400 catalogue previews
+(maximum 400 characters of source text each). Catalogue selection includes
+keyword matches, previous references, and diverse course/category records.
+When evidence is missing, stale, or needs a current check, the model can request
+read-only connector operations and plan again. It can discover courses and course
+areas, read discovered content files, assignment details/rubrics/own status and
+attachments, quiz metadata/own attempts, discussion forums/topics/posts, overview
+attachments, grades, announcements and calendar events. Supported document links
+can be followed from those resources. Discovery returns request-local handles;
+the model cannot supply arbitrary network URLs. New observations update the same
+inventory, without changing the sync course or traversal cursors. Freshly retrieved
+records receive priority in the next catalogue.
+
+Research allows at most two operations per planning turn, four read rounds and
+eight connector operations. A final planning turn must finish with available
+evidence or explain what is missing. Requests have a five-minute overall deadline;
+each operation may involve several bounded API/document reads. Calendar discovery
+covers the previous 30 and next 120 days. Live reads share the connector queue with
+sync, so an in-progress course pass can delay them. Use the UI opened by `dd2l start`
+to share its connector; standalone `npm run ui` acquires the inventory lock for each
+operation and reports if another command owns it.
+
+The model chooses source IDs and purpose-specific groups in relevance order,
+or asks for clarification. The server validates the plan, enforces the selected
+course scope, and rechecks current access before assembling sources.
+
+After planning, another model call generates a workspace program: title, short answer, HTML
+fragment (up to 60,000 characters), CSS (20,000), and a JavaScript function body
+(60,000), grounded in up to 24 selected excerpts of 8,000 characters each. The
+interface can be a planner, practice session, rubric explorer, form, diagram or
+calculator. It is not limited to a catalogue of prebuilt task widgets. All calls
+use the selected model and plan limits: normally two calls, up to five planning
+calls plus one canvas call when researching. Clarifications use only planning. Failed
+generation retains the verified source view; no retries or fallback models are
+billed automatically. Sources and cache coverage remain available from **Sources**.
+
+The implementation uses browser primitives rather than introducing React and a
+second agent runtime. The dedicated frame has an opaque origin and restrictive
+CSP. Only the trusted frame runtime touches the DOM. Generated JavaScript runs
+in a Blob worker with network access blocked, no DOM or frame navigation, opaque-origin storage restrictions,
+and a two-second response watchdog. Generated HTML is sanitized to semantic HTML,
+form controls and SVG geometry; scripts, embedded frames, event handlers and
+navigation/resource URLs are removed. CSS remains confined to the frame. This
+follows the isolated generative canvas pattern while keeping the current server
+and ChatGPT authentication path.
+
+The generated function receives `state`, `event`, and selected `sources`, and
+returns `{html, state}`. Events include click actions (`data-action`), named input
+changes and submissions. Named controls are saved/restored automatically in
+`state.inputs`; text controls accept up to 4,000 characters each. State must be
+JSON data under 32,000 characters and twelve levels deep. The app waits for
+pending worker updates before collecting progress for a follow-up. Generated
+programs can also keep tabs, revealed explanations, scenario values and other
+local state. Rendering applies the newest queued input so older results do not
+overwrite typing.
+
+A `data-source` button requests inspection of a selected source. The host
+validates that source ID, re-reads current access, then displays a trusted source
+panel and a Brightspace link. The generated program receives no credential,
+arbitrary fetch, file, submission, or host navigation capability. Source URLs
+come from dd2l, not generated HTML. API source references stop resolving after
+access is revoked.
+
+Follow-ups send the previous goal, selected IDs, bounded guidance summary, prior
+program, current progress and any runtime error to the selected model. Prior
+context and coursework are untrusted data in model instructions. **New search**
+and course changes clear the canvas and context; **Restart progress** reruns the
+current program with empty state. Progress is held in browser memory and clears
+on reload. Editing a prompt cancels generation without discarding the current
+canvas. The app enforces bounded JSON input and output, but a valid program may
+still contain factual, calculation or usability errors. Check its linked
+coursework and identify what to fix in a follow-up.
+
+Each explicit submission with a model selected authorizes live read-only discovery
+and sharing its results, those previews, excerpts, the previous program and local
+progress with OpenAI. Local mode sends
+none of them. Brightspace remains read-only. The model cannot invent missing
+course records or submit work. Catalogue coverage remains bounded and is shown
+in the source view when incomplete.
+
+School identity and current enrollment are checked for each operation; hidden or
+removed parents cannot authorize child reads. Login expiry and rate limiting stop
+further research, with the result shown in Sources; cached evidence may still be
+used with its freshness labels. This is an API/document read graph, not arbitrary
+browser clicking. It cannot start quizzes, submit assignments, enumerate class
+rosters, or sign into private LTI providers. Unsupported links remain gaps.
+
+This uses OpenAI's documented [local-app Sign in with ChatGPT flow](https://developers.openai.com/siwc/token-sharing-open-source), with PKCE, state/nonce and signed identity validation. A stable host ID and separate account registrations are saved under `%LOCALAPPDATA%\dd2l\llm\accounts.dpapi`, encrypted with Windows DPAPI. Refreshes are serialized across processes using a separate lock; the school sync can run alongside AI. Tokens stay on the server and never enter browser storage. `jose` handles JWT signature and claim verification. Remote Responses requests set `store: false` and `stream: true`; partial/failed streams do not become successful answers.
+
+Settings lists saved account/workspace registrations and supports switching, reauthorization and sign-out of the active account. Sign-out revokes its renewable session when possible and removes its local tokens; a failed remote revocation is reported. The non-secret registration and host ID remain for later sign-in. School CLI logout affects only school data; disconnect ChatGPT separately in the UI. Manage plan/app limits in [ChatGPT Settings → Usage](https://chatgpt.com/settings/usage). Usage shares the account's plan limits and may use credits according to settings you authorize there; dd2l never falls back to API-key billing. Eligibility, available models and limits are controlled by OpenAI.
+
+ChatGPT is the first supported subscription provider. There is no universal subscription login: other providers need separately verified authentication and plan-use support. Demo mode disables provider sign-in and AI requests and never loads AI credentials. Commercial or remotely hosted deployments need a separate access review against [OpenAI's integration requirements](https://developers.openai.com/siwc/request-client-id).
+
+For an isolated walkthrough with fictional data and no school login:
+
+```powershell
+npm run ui -- --demo
+```
+
+Demo mode is visibly labeled and never reads the real inventory. Try `recursion`, `memory`, or `syllabus`, filter by course, or browse Courses. Use `--port 4174` to run another instance. The server binds only to `127.0.0.1`, rejects foreign browser origins, and serves private responses without caching. Stop it with Ctrl+C when finished.
+
+`npm test` covers retrieval, cache access, widget layout validation, deadline/announcement projection and HTTP boundaries. `npm run ui:check` uses installed Chrome headlessly to check assets, core interactions, widget drag/move/resize/pin/removal and persistence, mobile overflow and error recovery; screenshots go in ignored `.dd2l/ui-*.png`. SF Pro uses the system font when available, with Segoe UI as the Windows fallback.
+
+## What is collected
+
+The audit enumerates course offerings, then reads the chosen course's content tree, assignment folders, quiz list, own grade values, announcements, discussion forums, own groups/sections, and calendar events. It traverses assignments and accessible content files in resumable batches, including own submissions, released feedback, rubric tables and attachments. Discussion forum/topic/post reads and file attachments have independent parent-specific cursors. `traversal` reports the batch limits; an unfinished batch is not reported as complete.
+
+Assignment traversal prioritizes graded and rubric-bearing folders, then continues through the others, up to 25 per pass. Feedback targets your verified user identity or your own resolved group; an unresolved group remains unknown. Full embedded rubric tables are retained, with a dedicated association lookup used when needed. Feedback denials are not interpreted as ungraded or unsubmitted work.
+
+Quiz discovery combines list entries, explicit content references, gradebook candidates and permitted grade/tool associations. A grade item named “Quiz” is only a candidate until a real quiz identifier/association is verified. Quiz metadata and attempts are read separately; attempts are explicitly filtered to the verified current user. Denied or unread attempts remain unknown. For events marked recurring, the connector requests the server's occurrence list rather than guessing dates or timezone rules; this route still needs a real accessible recurring-event example on onQ.
+
+Syllabus retrieval is part of normal audit/sync and can also run alone with `syllabus`. It reads the optional overview and its attachment, relevant module/topic descriptions, and file/HTML topics under syllabus or course-information modules. It preserves each source's location, parent context, retrieval time and current access/text status. An overview-specific 404 means `not_configured`; unrelated 404s retain their original meaning. An empty overview is not counted as a readable syllabus. Different documents remain separate instead of being silently merged into one authoritative text.
+
+Original permitted JSON fields are retained, with authentication/password fields and credential-bearing URL parameters redacted. Modern DOCX/PPTX/XLSX, PDF, HTML and plain text support local extraction; Office macros and formulas are not executed. Images and scanned PDF pages can use Windows OCR with an installed user-profile OCR language. OCR text is marked for review. Legacy binary Office files, arbitrary archives and encrypted documents are not supported by these readers.
+
+Documents have a 20 MiB read limit; raw bytes are retained only up to 2 MiB, while larger successfully parsed documents retain text and metadata. PDF workers have a 30-second deadline, 256 MiB JavaScript heap limit and 250-page limit. At most ten empty-text PDF pages per document are rendered for OCR, with a 16-million-pixel image limit. Text is capped at one million characters. Office expansion, HTML complexity and document/link counts are bounded; limits stay explicit as partial coverage. Syllabus retrieval processes up to 100 candidate sections and 20 document attempts per course. Ordinary traversal handles 20 content files per pass, five forums, five topics per selected forum, and two attachments per selected assignment/topic. API collections follow pagination with existing loop/page limits.
+
+Linked school documents use same-school session cookies only on approved content paths, or use their verified API topic IDs. Public reference documents are read only from explicitly supported hosts without school credentials. Source links are deduplicated; referenced websites are not recursively crawled through their citations/navigation. Surveys, self-enrollment and other activity actions are never activated by the document reader. Public YouTube caption retrieval preserves timestamps when the provider returns a caption track; sign-in/bot checks or absent captions remain unavailable. Private SharePoint, Teams, publisher/LTI content and other providers need separate readers/authorization. No assignments, grades, posts, quiz attempts, or completion states are written. Browser navigation may update normal school access timestamps.
+
+## Local data and app integration
+
+All runtime data lives outside this repository in `%LOCALAPPDATA%\dd2l`:
+
+| File | Purpose |
+| --- | --- |
+| `session.dpapi` | Session cookies, XSRF material, API token and verified identity, encrypted with Windows DPAPI for the current Windows user. |
+| `inventory.sqlite` | Private source payloads, extracted text/small files, traversal cursors, per-resource coverage, successful retrieval times and current outcomes. This database contains personal coursework and grades and is **not encrypted**. |
+| `summary.json` | Latest structural audit summary: counts, field names and coverage without course names, source IDs, grades or document bodies. Review before sharing. |
+| `syllabus-summary.json` | Latest syllabus-only command summary with readability, formats, coverage and unresolved counts. |
+| `worker.lock` | Prevents competing login/audit/sync processes; a dead process's lock is recovered on the next run. |
+
+`npm start -- logout` removes dd2l's saved session and local inventory. It does not sign out of other school applications. This is ordinary local deletion, not guaranteed forensic erasure or deletion of any copies you made.
+
+The importable core is `BrightspaceClient` in `src/client.mjs`, `Session` in `src/session.mjs`, `Connector`/`sync` in `src/connector.mjs`, and `Store` in `src/store.mjs`. `Connector.syllabus({ course })` uses the same retrieval logic as `audit` without changing the selected sync course. The CLI uses that same core. SQLite's `resources` table separates the latest observation from the last successful `data`, `last_success`, and `last_source`. Failed or partial reads preserve that data with its original source/window; a confirmed denial invalidates the affected cached resource. A complete enrollment read also invalidates cached courses no longer accessible. Data from different accounts cannot mix; run logout before switching accounts.
+
+Syllabus content lives in individual `syllabus_source` resource rows; the `syllabus` row is a catalog of source keys and current outcomes, not a duplicate of every document's text. A failed fetch or extraction retains the source's prior successful data as stale. Explicit access restrictions invalidate that source's cached data, and a documented missing overview clears the overview/attachment cache. Catalog readability means some source text was retrieved, while `textCoverageComplete` also accounts for unsupported formats, restrictions, read limits and unexpanded links. Neither field establishes that every possible syllabus location was discovered.
+
+An audit can complete successfully as a command while reporting `complete: false`: resource-level denials, unavailable routes, or partial collections remain visible. A successful collection read establishes coverage of that endpoint, not of every activity the website or an external tool may contain.
+
+Persistent semantic indexing, additional model providers, private course-content provider integrations and unattended Windows startup remain later milestones.
+
+Do not commit credentials, session cookies, access tokens, downloaded coursework, grades, or classmates' personal information. Discovery evidence should contain access outcomes and field names rather than private payloads.

package/package.json

@@ -1,6 +1,56 @@
-{
-  "name": "@ivanbard/dd2l",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@ivanbard/dd2l",
+  "version": "0.1.1",
+  "description": "A local, read-only student companion for Queen's onQ: sync coursework, search sources, and optionally connect ChatGPT.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivanbard/dd2l.git"
+  },
+  "homepage": "https://github.com/ivanbard/dd2l#readme",
+  "bugs": {
+    "url": "https://github.com/ivanbard/dd2l/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "bin": {
+    "dd2l": "bin/dd2l.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "ui/",
+    "docs/README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "start": "node src/cli.mjs",
+    "setup": "node src/cli.mjs setup",
+    "ui": "node src/ui-server.mjs",
+    "ui:check": "node scripts/check-ui.mjs && node scripts/check-canvas.mjs",
+    "test": "node --test",
+    "package:check": "node scripts/check-package.mjs",
+    "release:check": "npm test && npm run ui:check && npm run package:check",
+    "prepublishOnly": "npm run release:check",
+    "login": "node src/cli.mjs login",
+    "audit": "node src/cli.mjs audit",
+    "sync": "node src/cli.mjs sync",
+    "status": "node src/cli.mjs status",
+    "soak": "node scripts/soak-sync.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@napi-rs/canvas": "^1.0.13",
+    "fflate": "^0.8.3",
+    "htmlparser2": "12.0.0",
+    "jose": "^6.2.15",
+    "playwright-core": "1.58.2",
+    "unpdf": "2.0.0"
+  }
+}

package/src/app-runner.mjs

@@ -0,0 +1,58 @@
+import { execFile } from 'node:child_process';
+import { createUiServer } from './ui-server.mjs';
+import { sync } from './connector.mjs';
+import { log as terminalLog, spinner } from '@clack/prompts';
+
+function openBrowser(url) {
+  return new Promise((resolve, reject) => {
+    execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+      `Start-Process -FilePath '${url}' -WindowStyle Hidden`], { windowsHide: true, timeout: 15_000 },
+    error => error ? reject(error) : resolve());
+  });
+}
+
+export async function runApp(connector, { onUpdate, server,
+  open = openBrowser, signals = process, port = 4173, log = terminalLog.info } = {}) {
+  const controller = new AbortController();
+  server ??= createUiServer({ connector, shutdownSignal: controller.signal });
+  const progress = process.stdout.isTTY ? spinner({ signal: controller.signal }) : null;
+  let firstPass = true;
+  const stop = () => controller.abort();
+  signals.on('SIGINT', stop);
+  signals.on('SIGTERM', stop);
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, '127.0.0.1', resolve);
+    });
+    const url = `http://127.0.0.1:${server.address().port}`;
+    log(`Your workspace → ${url}\nKeep this terminal open; Ctrl+C stops the app and sync.`);
+    try { await open(url); }
+    catch { log(`Could not open your browser. Open ${url} manually.`); }
+    log('Collecting up to 5 courses per pass, every 15 minutes.\nThe app may be empty until the first batch is ready.');
+    progress?.start('Collecting your first batch of coursework');
+    await sync(connector, { all: true }, { signal: controller.signal, onUpdate: async summary => {
+      await onUpdate?.(summary);
+      const message = summary.state === 'retry_wait'
+        ? 'Collection delayed · will retry automatically'
+        : 'Coursework saved · reopen Courses or search to see updates';
+      if (progress && firstPass) {
+        if (summary.state === 'retry_wait') { progress.clear(); terminalLog.warn(message); }
+        else progress.stop(message);
+      }
+      else log(message);
+      if (firstPass && summary.state !== 'retry_wait') {
+        log('Local search is ready. Connect ChatGPT in Settings for AI answers.');
+      }
+      firstPass = false;
+    } });
+  } catch (error) {
+    progress?.error('Collection stopped');
+    throw error;
+  } finally {
+    progress?.clear();
+    signals.off('SIGINT', stop);
+    signals.off('SIGTERM', stop);
+    await new Promise(resolve => { server.close(resolve); server.closeAllConnections(); });
+  }
+}