@ivanbard/dd2l 0.1.0 → 0.1.2

package/src/cli-banner.mjs

@@ -0,0 +1,58 @@
+import { styleText } from 'node:util';
+
+const bayer = [
+  [0, 32, 8, 40, 2, 34, 10, 42],
+  [48, 16, 56, 24, 50, 18, 58, 26],
+  [12, 44, 4, 36, 14, 46, 6, 38],
+  [60, 28, 52, 20, 62, 30, 54, 22],
+  [3, 35, 11, 43, 1, 33, 9, 41],
+  [51, 19, 59, 27, 49, 17, 57, 25],
+  [15, 47, 7, 39, 13, 45, 5, 37],
+  [63, 31, 55, 23, 61, 29, 53, 21],
+];
+const dots = [[0, 1, 2, 6], [3, 4, 5, 7]];
+const glyphs = {
+  d: ['00001', '00001', '01111', '10001', '10001', '10001', '01111'],
+  2: ['01110', '10001', '00001', '00010', '00100', '01000', '11111'],
+  l: ['11000', '01000', '01000', '01000', '01000', '01000', '00110'],
+};
+const wordmark = Array.from({ length: 8 }, (_, y) =>
+  [...'dd2l'].map(letter => glyphs[letter][y] ?? '00000').join('0') + '0');
+
+function raster(width, row, pixel) {
+  return Array.from({ length: width }, (_, cell) => {
+    let mask = 0;
+    for (let column = 0; column < 2; column++) {
+      for (let dot = 0; dot < 4; dot++) {
+        if (pixel(cell * 2 + column, row * 4 + dot)) mask |= 1 << dots[column][dot];
+      }
+    }
+    // Keep even the dense areas on the dot grid to avoid a block-to-Braille seam.
+    return String.fromCodePoint(0x2800 + mask);
+  }).join('');
+}
+
+function bar(width, row, mirrored = false) {
+  return raster(width, row, (x, y) => {
+    if (mirrored) x = width * 2 - 1 - x;
+    const t = Math.min(1, (x + 0.5) / (width * 2 * 0.85));
+    const density = t * t * (3 - 2 * t);
+    return density > (bayer[y][x % 8] + 0.5) / 64;
+  });
+}
+
+export function renderBanner(columns = 80) {
+  // Leave the last column free so the terminal doesn't wrap the banner.
+  const width = Math.max(1, columns - 1);
+  if (width < 31) {
+    const title = 'dd2l'.slice(0, width);
+    return ' '.repeat(Math.floor((width - title.length) / 2)) + styleText('bold', title);
+  }
+  const labelWidth = wordmark[0].length / 2;
+  const barWidth = Math.min(20, Math.floor((width - labelWidth - 4) / 2));
+  const padding = ' '.repeat(Math.floor((width - barWidth * 2 - labelWidth - 4) / 2));
+  return [0, 1].map(row => {
+    const label = raster(labelWidth, row, (x, y) => wordmark[y][x] === '1');
+    return `${padding}${styleText('blueBright', bar(barWidth, row))}  ${label}  ${styleText('blueBright', bar(barWidth, row, true))}`;
+  }).join('\n');
+}

package/src/cli.mjs

@@ -1,14 +1,15 @@
 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 { select, text, isCancel, cancel, log, outro } from '@clack/prompts';
+import { BrightspaceClient, SCHOOL, schoolOrigin } 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';
+import { renderBanner } from './cli-banner.mjs';
 
-const help = `dd2l — direct, read-only Queen's onQ connector (Windows, Node 24+)
+const help = `dd2l — direct, read-only Brightspace 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
@@ -22,7 +23,7 @@ dd2l sync --all                     Rotate through all accessible courses in bou
 dd2l status                         Show coverage and last successful reads
 dd2l logout                         Delete dd2l's session and local inventory
 
-Without a global install: npx dd2l <command>.
+Without a global install: npx @ivanbard/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)
@@ -43,18 +44,25 @@ async function main() {
   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');
+  let selectedOrigin;
+  if (['setup', 'start'].includes(command)) console.log(`\n${renderBanner(process.stdout.columns)}\n`);
   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(); }
+    log.info('Read-only access. Coursework is stored unencrypted on this PC.');
+    const school = await select({ message: 'Select your school', options: [
+      { value: SCHOOL, label: 'Queen\'s University', hint: 'onQ · connect and collect coursework' },
+      { value: 'not-listed', label: 'My school isn\'t listed', hint: 'enter a Brightspace URL' },
+    ] });
+    if (isCancel(school)) { cancel('Setup cancelled. No school connection was made.'); return; }
+    if (school === 'not-listed') {
+      const url = await text({ message: 'Your school\'s Brightspace URL', placeholder: 'your-school.brightspace.com',
+        validate: value => { try { schoolOrigin(value); } catch (error) { return error.message; } },
+      });
+      if (isCancel(url)) { cancel('Setup cancelled. No school connection was made.'); return; }
+      selectedOrigin = schoolOrigin(url);
+      log.info('Custom school · compatibility has not been verified.');
+      log.info('Help add your school: open an issue with its name and URL.\nhttps://github.com/ivanbard/dd2l/issues/new');
+    } else selectedOrigin = school;
   }
   await mkdir(directory, { recursive: true });
   // Status is read-only and can inspect a running worker without taking its lock.
@@ -62,18 +70,27 @@ ChatGPT is optional: connect it later in Settings. Local search stays on this co
   let store;
   try {
     store = new Store(directory);
-    const session = new Session(directory);
-    const client = new BrightspaceClient(session);
+    const origin = ['status', 'logout'].includes(command) ? SCHOOL : schoolOrigin(selectedOrigin ?? store.getMeta('school_origin') ?? SCHOOL);
+    const session = new Session(directory, { origin });
+    const client = new BrightspaceClient(session, { origin });
     const connector = new Connector(client, store);
     if (command === 'login' || command === 'setup') {
-      await login(session, client, { expectedAccount: store.getMeta('account') });
+      if (command === 'setup') {
+        log.step(`Sign in to ${origin === SCHOOL ? 'Queen\'s onQ' : new URL(origin).hostname}`);
+        log.info('Complete sign-in and MFA in Chrome. Your password is never saved.\nSession credentials are encrypted for your Windows account.');
+      }
+      await login(session, client, { expectedAccount: store.getMeta('account'),
+        ...(command === 'setup' ? { onProgress: () => {} } : {}) });
+      store.meta('school_origin', origin);
+      if (command === 'setup') log.success('School connected · identity verified');
       store.meta('state', { state: 'ready', updatedAt: new Date().toISOString() });
     }
     if (command === 'start' || command === 'setup') {
+      if (command === 'setup') log.info(`Coursework and grades will be cached in:\n${directory}`);
       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.');
       } });
+      outro('dd2l stopped. Your cached coursework is saved.');
     } else if (command === 'courses') {
       const { enrollments } = await connector.courses();
       console.log(JSON.stringify({ complete: enrollments.complete, courses: enrollments.data.map(item => ({
@@ -117,4 +134,9 @@ ChatGPT is optional: connect it later in Settings. Local search stays on this co
   } finally { store?.close(); await release(); }
 }
 
-main().catch(error => { console.error(`${error.code || 'error'}: ${error.message}`); process.exitCode = 1; });
+main().catch(error => {
+  const message = `${error.code || 'error'}: ${error.message}`;
+  if (['setup', 'start'].includes(process.argv[2]) && process.stdout.isTTY) log.error(message);
+  else console.error(message);
+  process.exitCode = 1;
+});

package/src/client.mjs

@@ -1,137 +1,150 @@
-export const SCHOOL = 'https://onq.queensu.ca';
-
-export class AccessError extends Error {
-  constructor(code, message, { status, retryAfter = 0 } = {}) {
-    super(message);
-    this.code = code;
-    this.status = status;
-    this.retryAfter = retryAfter;
-  }
-}
-
-// Never attach response bodies, headers, or credential-bearing URLs to errors.
-export async function request(url, options = {}, fetchImpl = fetch) {
-  let response;
-  try {
-    response = await fetchImpl(url, {
-      ...options, redirect: 'manual', signal: AbortSignal.timeout(30_000),
-    });
-  } catch {
-    throw new AccessError('retry_wait', 'Network request failed or timed out.');
-  }
-  return checkedResponse(response, url);
-}
-
-export function checkedResponse(response, url) {
-  if (response.status === 401) throw new AccessError('needs_login', 'School sign-in is required.', { status: 401 });
-  if (response.status >= 300 && response.status < 400) {
-    const target = new URL(response.headers.get('location') || '/', url);
-    const login = /\/d2l\/(?:login|lms\/auth)/i.test(target.pathname) || target.hostname === 'login.microsoftonline.com';
-    throw new AccessError(login ? 'needs_login' : 'redirect', login ? 'School sign-in is required.' : 'Unexpected redirect was not followed.', { status: response.status });
-  }
-  if (response.status === 403) throw new AccessError('denied', 'Brightspace denied access to this resource.', { status: 403 });
-  if (response.status === 404) throw new AccessError('unavailable', 'Resource or API route is unavailable; absence is not established.', { status: 404 });
-  if (response.status === 429 || response.status >= 500) {
-    const raw = response.headers.get('retry-after');
-    const seconds = raw && /^\d+$/.test(raw) ? Number(raw) : Math.max(0, (Date.parse(raw) - Date.now()) / 1000);
-    throw new AccessError('retry_wait', `Brightspace returned HTTP ${response.status}.`, {
-      status: response.status, retryAfter: Number.isFinite(seconds) ? seconds * 1000 : 0,
-    });
-  }
-  if (!response.ok) throw new AccessError('failed', `Brightspace returned HTTP ${response.status}.`, { status: response.status });
-  return response;
-}
-
-export async function readJson(response) {
-  const text = await response.text();
-  if (!/\bapplication\/(?:[\w.+-]*\+)?json\b/i.test(response.headers.get('content-type') || '')) {
-    if (text.includes('/d2l/login?sessionExpired=1')) throw new AccessError('needs_login', 'School session has expired.');
-    throw new AccessError('invalid_response', 'Expected JSON; received a different response format.');
-  }
-  try { return JSON.parse(text); }
-  catch { throw new AccessError('invalid_response', 'Brightspace returned invalid JSON.'); }
-}
-
-export function apiUrl(origin, path) {
-  const url = new URL(path, origin);
-  if (url.origin !== origin || url.username || url.password || url.hash || !url.pathname.startsWith('/d2l/api/')) {
-    throw new AccessError('invalid_link', 'Refused a link outside this school’s API.');
-  }
-  return url;
-}
-
-export class BrightspaceClient {
-  constructor(session, { origin = SCHOOL, fetchImpl = fetch } = {}) {
-    this.session = session;
-    this.origin = new URL(origin).origin;
-    if (!this.origin.startsWith('https://')) throw new Error('School origin must use HTTPS.');
-    this.fetch = fetchImpl;
-  }
-
-  async versions() {
-    const data = await readJson(await request(`${this.origin}/d2l/api/versions/`, {}, this.fetch));
-    const versions = {};
-    for (const product of ['lp', 'le']) {
-      const value = data?.find?.(item => item.ProductCode === product)?.LatestVersion;
-      if (!/^\d+\.\d+$/.test(value || '')) throw new AccessError('invalid_response', 'Missing supported API versions.');
-      versions[product] = value;
-    }
-    return versions;
-  }
-
-  async response(path) {
-    const url = apiUrl(this.origin, path);
-    let token = await this.session.token();
-    for (let attempt = 0; attempt < 2; attempt++) {
-      try {
-        return await request(url, { headers: { authorization: `Bearer ${token}`, accept: 'application/json' } }, this.fetch);
-      } catch (error) {
-        if (error.code !== 'needs_login' || attempt) throw error;
-        token = await this.session.token(token);
-      }
-    }
-  }
-
-  async get(path) { return readJson(await this.response(path)); }
-
-  async collection(path) {
-    const data = [];
-    const seen = new Set();
-    let next = apiUrl(this.origin, path);
-    let pages = 0;
-    try {
-      while (next) {
-        if (pages === 200 || seen.has(next.href)) throw new AccessError('partial', 'Pagination stopped at a loop or page limit.');
-        seen.add(next.href);
-        const result = await this.get(next.href);
-        pages++;
-        if (Array.isArray(result)) {
-          data.push(...result);
-          next = null;
-        } else if (Array.isArray(result?.Items) && result.PagingInfo && typeof result.PagingInfo.HasMoreItems === 'boolean') {
-          data.push(...result.Items);
-          if (!result.PagingInfo.HasMoreItems) next = null;
-          else {
-            const bookmark = result.PagingInfo.Bookmark;
-            if (typeof bookmark !== 'string' || !bookmark) throw new AccessError('partial', 'More pages were advertised without a bookmark.');
-            next = apiUrl(this.origin, path);
-            next.searchParams.set('bookmark', bookmark);
-          }
-        } else if (Array.isArray(result?.Objects) && Object.hasOwn(result, 'Next')) {
-          data.push(...result.Objects);
-          if (!result.Next) next = null;
-          else if (typeof result.Next !== 'string') throw new AccessError('invalid_response', 'Invalid next-page marker.');
-          else if (/^(?:https?:|\/)/i.test(result.Next)) next = apiUrl(this.origin, result.Next);
-          else {
-            next = apiUrl(this.origin, path);
-            next.searchParams.set('bookmark', result.Next);
-          }
-        } else throw new AccessError('invalid_response', 'Unrecognized collection response; completeness cannot be established.');
-      }
-      return { data, pages, complete: true };
-    } catch (error) {
-      if (!(error instanceof AccessError) || error.code === 'needs_login' || error.status === 429 || !pages) throw error;
-      return { data, pages, complete: false, error: error.code, message: error.message, retryAfter: error.retryAfter };
-    }
-  }
-}
+export const SCHOOL = 'https://onq.queensu.ca';
+
+export function schoolOrigin(value) {
+  const message = 'Enter a valid Brightspace address (HTTPS only, no embedded username or password).';
+  if (typeof value !== 'string' || /[\u0000-\u0020\u007f\\]/.test(value.trim())) throw new Error(message);
+  const address = value.trim().replace(/^\/\//, '');
+  let url;
+  try { url = new URL(/^[a-z][a-z\d+.-]*:\/\//i.test(address) ? address : `https://${address}`); } catch { throw new Error(message); }
+  if (url.protocol !== 'https:' || url.username || url.password) throw new Error(message);
+  return url.origin;
+}
+
+export class AccessError extends Error {
+  constructor(code, message, { status, retryAfter = 0 } = {}) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}
+
+// Never attach response bodies, headers, or credential-bearing URLs to errors.
+export async function request(url, options = {}, fetchImpl = fetch) {
+  options.signal?.throwIfAborted();
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      ...options, redirect: 'manual', signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+    });
+  } catch {
+    options.signal?.throwIfAborted();
+    throw new AccessError('retry_wait', 'Network request failed or timed out.');
+  }
+  return checkedResponse(response, url);
+}
+
+export function checkedResponse(response, url) {
+  if (response.status === 401) throw new AccessError('needs_login', 'School sign-in is required.', { status: 401 });
+  if (response.status >= 300 && response.status < 400) {
+    const target = new URL(response.headers.get('location') || '/', url);
+    const login = /\/d2l\/(?:login|lms\/auth)/i.test(target.pathname) || target.hostname === 'login.microsoftonline.com';
+    throw new AccessError(login ? 'needs_login' : 'redirect', login ? 'School sign-in is required.' : 'Unexpected redirect was not followed.', { status: response.status });
+  }
+  if (response.status === 403) throw new AccessError('denied', 'Brightspace denied access to this resource.', { status: 403 });
+  if (response.status === 404) throw new AccessError('unavailable', 'Resource or API route is unavailable; absence is not established.', { status: 404 });
+  if (response.status === 429 || response.status >= 500) {
+    const raw = response.headers.get('retry-after');
+    const seconds = raw && /^\d+$/.test(raw) ? Number(raw) : Math.max(0, (Date.parse(raw) - Date.now()) / 1000);
+    throw new AccessError('retry_wait', `Brightspace returned HTTP ${response.status}.`, {
+      status: response.status, retryAfter: Number.isFinite(seconds) ? seconds * 1000 : 0,
+    });
+  }
+  if (!response.ok) throw new AccessError('failed', `Brightspace returned HTTP ${response.status}.`, { status: response.status });
+  return response;
+}
+
+export async function readJson(response) {
+  const text = await response.text();
+  if (!/\bapplication\/(?:[\w.+-]*\+)?json\b/i.test(response.headers.get('content-type') || '')) {
+    if (text.includes('/d2l/login?sessionExpired=1')) throw new AccessError('needs_login', 'School session has expired.');
+    throw new AccessError('invalid_response', 'Expected JSON; received a different response format.');
+  }
+  try { return JSON.parse(text); }
+  catch { throw new AccessError('invalid_response', 'Brightspace returned invalid JSON.'); }
+}
+
+export function apiUrl(origin, path) {
+  const url = new URL(path, origin);
+  if (url.origin !== origin || url.username || url.password || url.hash || !url.pathname.startsWith('/d2l/api/')) {
+    throw new AccessError('invalid_link', 'Refused a link outside this school’s API.');
+  }
+  return url;
+}
+
+export class BrightspaceClient {
+  constructor(session, { origin = SCHOOL, fetchImpl = fetch, signal } = {}) {
+    this.session = session;
+    this.origin = schoolOrigin(origin);
+    this.fetch = fetchImpl;
+    this.signal = signal;
+  }
+
+  async versions() {
+    const data = await readJson(await request(`${this.origin}/d2l/api/versions/`, { signal: this.signal }, this.fetch));
+    const versions = {};
+    for (const product of ['lp', 'le']) {
+      const value = data?.find?.(item => item.ProductCode === product)?.LatestVersion;
+      if (!/^\d+\.\d+$/.test(value || '')) throw new AccessError('invalid_response', 'Missing supported API versions.');
+      versions[product] = value;
+    }
+    return versions;
+  }
+
+  async response(path) {
+    this.signal?.throwIfAborted();
+    const url = apiUrl(this.origin, path);
+    let token = await this.session.token();
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        return await request(url, { headers: { authorization: `Bearer ${token}`, accept: 'application/json' }, signal: this.signal }, this.fetch);
+      } catch (error) {
+        if (error.code !== 'needs_login' || attempt) throw error;
+        token = await this.session.token(token);
+      }
+    }
+  }
+
+  async get(path) { return readJson(await this.response(path)); }
+
+  async collection(path) {
+    const data = [];
+    const seen = new Set();
+    let next = apiUrl(this.origin, path);
+    let pages = 0;
+    try {
+      while (next) {
+        if (pages === 200 || seen.has(next.href)) throw new AccessError('partial', 'Pagination stopped at a loop or page limit.');
+        seen.add(next.href);
+        const result = await this.get(next.href);
+        pages++;
+        if (Array.isArray(result)) {
+          data.push(...result);
+          next = null;
+        } else if (Array.isArray(result?.Items) && result.PagingInfo && typeof result.PagingInfo.HasMoreItems === 'boolean') {
+          data.push(...result.Items);
+          if (!result.PagingInfo.HasMoreItems) next = null;
+          else {
+            const bookmark = result.PagingInfo.Bookmark;
+            if (typeof bookmark !== 'string' || !bookmark) throw new AccessError('partial', 'More pages were advertised without a bookmark.');
+            next = apiUrl(this.origin, path);
+            next.searchParams.set('bookmark', bookmark);
+          }
+        } else if (Array.isArray(result?.Objects) && Object.hasOwn(result, 'Next')) {
+          data.push(...result.Objects);
+          if (!result.Next) next = null;
+          else if (typeof result.Next !== 'string') throw new AccessError('invalid_response', 'Invalid next-page marker.');
+          else if (/^(?:https?:|\/)/i.test(result.Next)) next = apiUrl(this.origin, result.Next);
+          else {
+            next = apiUrl(this.origin, path);
+            next.searchParams.set('bookmark', result.Next);
+          }
+        } else throw new AccessError('invalid_response', 'Unrecognized collection response; completeness cannot be established.');
+      }
+      return { data, pages, complete: true };
+    } catch (error) {
+      if (!(error instanceof AccessError) || error.code === 'needs_login' || error.status === 429 || !pages) throw error;
+      return { data, pages, complete: false, error: error.code, message: error.message, retryAfter: error.retryAfter };
+    }
+  }
+}