@ivanbard/dd2l 0.0.0-stage → 0.1.0

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,83 @@
-# 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
+- optionally connect ChatGPT for answers grounded in matching course excerpts
+
+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.
+
+## School not listed?
+If your school/educational faculty uses D2L Brightspace and is not available during setup, please open an issue in the GitHub repo with some details as to your 
+provider's Brightspace link and faculty name. Feel free to also create a PR if you have added your own solution to your school not being listed.
+
+## 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 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 dd2l start`. If the school session expires, stop the app and
+run `npx dd2l setup` again. Optional ChatGPT sign-in is in Settings.
+
+Alternatively, install globally with `npm install -g 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 question and matching course 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,130 @@
+# 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
+
+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 dd2l setup` and
+`npx 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 beside the course selector defaults to **Local search**, which matches keywords; choosing a connected ChatGPT model generates grounded answers when you submit.
+
+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. The small mode dropdown below the prompt starts on **Local search**, even with a connected account. Choose a model to see the coursework-sharing notice, then press Enter or the send button to ask it. Changing the selection never submits a prompt. Select **Local search** to return to local retrieval; reloading or starting a new search also restores that default. Plan and usage information stays in Settings.
+
+Each AI request sends the question and up to eight matching excerpts (at most 700 characters each), including titles, course names, retrieval dates and stale-cache labels, to OpenAI. The answer displays those sources with numbered references. The model is instructed to use only this evidence and report gaps; verify generated claims against the excerpts. Keyword retrieval can miss relevant material. No tool execution, Brightspace credentials, complete inventory upload, or persistent conversation history is provided. Each submission with an AI model selected grants permission for that answer; local mode never sends the question to an AI provider. Editing the question or changing modes or courses cancels an in-flight answer.
+
+AI answers can compose interactive checklists, comparison tables, and grouped source cards in the same matte printed style as the homescreen widgets. The selected model chooses useful sections or plain text for a simple question. The Responses request uses [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) with a bounded JSON schema; the app validates the result and citation numbers before rendering trusted components. No model-generated HTML, scripts, URLs or styling execute. Invalid layouts fall back to a bounded text summary and the available sources, with a notice; incomplete streams still fail rather than appearing successful. Provider refusals display as text. A model must support the structured-output format; errors do not trigger another model or a second billed request.
+
+Checklist checks and progress belong to the current answer and reset on a new question. They do not update Brightspace or save to your homescreen. Every generated item or comparison row links to supplied source excerpts; stale cache labels remain visible. Valid structure and citations do not prove factual correctness or complete course coverage. Source retrieval still uses the existing keyword search and its limits.
+
+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.
+
+Improved semantic retrieval, 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,55 @@
-{
-  "name": "@ivanbard/dd2l",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@ivanbard/dd2l",
+  "version": "0.1.0",
+  "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",
+    "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": {
+    "@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,35 @@
+import { execFile } from 'node:child_process';
+import { createUiServer } from './ui-server.mjs';
+import { sync } from './connector.mjs';
+
+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 = createUiServer(),
+  open = openBrowser, signals = process, port = 4173, log = console.log } = {}) {
+  const controller = new AbortController();
+  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(`dd2l: ${url}\nKeep this terminal open. Ctrl+C stops the app and sync.`);
+    log('Collecting coursework now; the first view may be empty. Collection is incremental, up to five courses per pass, every 15 minutes.');
+    try { await open(url); }
+    catch { log(`Could not open your browser. Open ${url} manually.`); }
+    await sync(connector, { all: true }, { signal: controller.signal, onUpdate });
+  } finally {
+    signals.off('SIGINT', stop);
+    signals.off('SIGTERM', stop);
+    await new Promise(resolve => server.close(resolve));
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,120 @@
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { BrightspaceClient } from './client.mjs';
+import { Session, login, atomicWrite } from './session.mjs';
+import { Store, lock } from './store.mjs';
+import { Connector, sync } from './connector.mjs';
+import { runApp } from './app-runner.mjs';
+
+const help = `dd2l — direct, read-only Queen's onQ connector (Windows, Node 24+)
+
+dd2l setup                          Guided school sign-in, then open the app and sync
+dd2l start                          Open the app and sync with your saved school session
+dd2l login                          Open Chrome for school sign-in and MFA
+dd2l courses                        List your course IDs and names
+dd2l audit [--course ID]             Audit one course (defaults to an accessible active course)
+dd2l audit --all                    Advance the all-course pass (five courses per run)
+dd2l syllabus [--course ID]          Retrieve syllabus/course-information sources and text
+dd2l sync [--course ID]              Repeat that audit every 15 minutes until Ctrl+C
+dd2l sync --all                     Rotate through all accessible courses in bounded passes
+dd2l status                         Show coverage and last successful reads
+dd2l logout                         Delete dd2l's session and local inventory
+
+Without a global install: npx dd2l <command>.
+From source: npm start -- <command>, or npm run setup.
+
+audit/sync: --from ISO --to ISO      Calendar window (default: past 30 / next 120 days)
+syllabus: --course ID               Choose the course without changing the sync selection
+
+Data: %LOCALAPPDATA%\\dd2l (session protected for this Windows user; inventory is private local data).
+ChatGPT is optional in the UI; connector commands make no external model calls.`;
+
+async function main() {
+  const { positionals, values } = parseArgs({ allowPositionals: true, options: {
+    course: { type: 'string' }, from: { type: 'string' }, to: { type: 'string' }, all: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  const command = positionals[0];
+  if (values.help || !command) { console.log(help); return; }
+  if (positionals.length > 1 || !['setup', 'start', 'login', 'courses', 'audit', 'syllabus', 'sync', 'status', 'logout'].includes(command)) throw new Error('Unknown command. Run dd2l --help.');
+  if (!['audit', 'sync', 'syllabus'].includes(command) && Object.keys(values).length) throw new Error('Date/course options apply only to audit, syllabus and sync.');
+  if (command === 'syllabus' && (values.from || values.to)) throw new Error('Calendar date options apply only to audit and sync.');
+  if (values.all && (!['audit', 'sync'].includes(command) || values.course)) throw new Error('--all applies to audit/sync and cannot be combined with --course.');
+  if (process.platform !== 'win32' || !process.env.LOCALAPPDATA) throw new Error('This first connector requires Windows with LOCALAPPDATA.');
+  const directory = join(process.env.LOCALAPPDATA, 'dd2l');
+  if (command === 'setup') {
+    console.log(`Welcome to dd2l. Requires Google Chrome and a Queen's onQ account.
+School sign-in and MFA happen in a separate Chrome window; no school password is saved.
+Session credentials are encrypted for your Windows account. Coursework and grades
+are cached unencrypted in ${directory}. The connector is read-only.
+ChatGPT is optional: connect it later in Settings. Local search stays on this computer.`);
+    if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Run dd2l setup in an interactive terminal.');
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const answer = await prompt.question('Connect onQ and start collecting coursework? [y/N] ');
+      if (!/^y(?:es)?$/i.test(answer.trim())) { console.log('Setup cancelled. No school connection was made.'); return; }
+    } finally { prompt.close(); }
+  }
+  await mkdir(directory, { recursive: true });
+  // Status is read-only and can inspect a running worker without taking its lock.
+  const release = command === 'status' ? async () => {} : await lock(directory);
+  let store;
+  try {
+    store = new Store(directory);
+    const session = new Session(directory);
+    const client = new BrightspaceClient(session);
+    const connector = new Connector(client, store);
+    if (command === 'login' || command === 'setup') {
+      await login(session, client, { expectedAccount: store.getMeta('account') });
+      store.meta('state', { state: 'ready', updatedAt: new Date().toISOString() });
+    }
+    if (command === 'start' || command === 'setup') {
+      await runApp(connector, { onUpdate: async summary => {
+        await atomicWrite(join(directory, 'summary.json'), JSON.stringify(summary, null, 2));
+        console.log(summary.state === 'retry_wait' ? 'Collection delayed; will retry automatically.' : 'Coursework pass saved. Reopen Courses or search to see updates.');
+      } });
+    } else if (command === 'courses') {
+      const { enrollments } = await connector.courses();
+      console.log(JSON.stringify({ complete: enrollments.complete, courses: enrollments.data.map(item => ({
+        id: item.OrgUnit?.Id, name: item.OrgUnit?.Name, active: item.Access?.IsActive, canAccess: item.Access?.CanAccess,
+      })) }, null, 2));
+    } else if (command === 'syllabus') {
+      const summary = await connector.syllabus(values);
+      await atomicWrite(join(directory, 'syllabus-summary.json'), JSON.stringify(summary, null, 2));
+      console.log(JSON.stringify(summary, null, 2));
+    } else if (command === 'audit' || command === 'sync') {
+      const report = async summary => {
+        await atomicWrite(join(directory, 'summary.json'), JSON.stringify(summary, null, 2));
+        console.log(JSON.stringify(summary, null, 2));
+      };
+      if (command === 'audit') await report(await connector.audit(values));
+      else {
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        try { await sync(connector, values, { signal: controller.signal, onUpdate: report }); }
+        finally { process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+      }
+    } else if (command === 'status') console.log(JSON.stringify(store.status(), null, 2));
+    else if (command === 'logout') {
+      await rm(session.path, { force: true });
+      await rm(join(directory, 'summary.json'), { force: true });
+      await rm(join(directory, 'syllabus-summary.json'), { force: true });
+      store.clear();
+      store.close();
+      store = null;
+      for (const name of ['inventory.sqlite', 'inventory.sqlite-wal', 'inventory.sqlite-shm']) {
+        await rm(join(directory, name), { force: true });
+      }
+      console.log('dd2l session and inventory removed. School sign-in on other apps is unchanged.');
+    }
+  } catch (error) {
+    if (store && error.code === 'needs_login') store.meta('state', { state: 'needs_login', updatedAt: new Date().toISOString() });
+    if (error.code === 'needs_login' && ['start', 'setup'].includes(command)) error.message += ' Run dd2l setup to sign in and restart.';
+    throw error;
+  } finally { store?.close(); await release(); }
+}
+
+main().catch(error => { console.error(`${error.code || 'error'}: ${error.message}`); process.exitCode = 1; });