brightspace-mcp-server 3.3.0 → 3.4.1

package/README.md

@@ -117,6 +117,7 @@ npx -y brightspace-mcp-server@latest auth
 | Roster | "Who are the TAs for ECE 264?" · "Get me my instructor's email" |
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |
 | Video transcripts | "What did the professor say about pinch-off in Tuesday's lecture recording?" · "Summarize last week's BoilerCast video" — works for Kaltura and YouTube embeds; other platforms report that they aren't supported yet |
+| Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, and whether a credential is stored, without contacting Brightspace or revealing secrets |
 | Planning | "Build me a study schedule based on my upcoming due dates" · "Which class needs the most attention right now?" — pulls from assignments, quizzes, and graded discussion topics (any topic with a due date) |
 
 

package/build/api/cache.js

@@ -22,12 +22,25 @@ export class TTLCache {
             timerId.unref();
         }
         // Store entry
-        this.cache.set(key, { data: value, timerId });
+        this.cache.set(key, { data: value, timerId, storedAt: Date.now() });
     }
     get(key) {
         const entry = this.cache.get(key);
         return entry?.data;
     }
+    /**
+     * How long ago this key was written, in milliseconds, or undefined when it
+     * is not cached.
+     *
+     * One key can be written under several TTLs: two tools ask for the same
+     * path with different freshness requirements. An entry another caller kept
+     * alive for an hour is still too old for a caller that asked for ten
+     * minutes, and only its age can say so.
+     */
+    ageOf(key) {
+        const entry = this.cache.get(key);
+        return entry ? Date.now() - entry.storedAt : undefined;
+    }
     has(key) {
         return this.cache.has(key);
     }

package/build/api/client.js

@@ -183,9 +183,18 @@ export class D2LApiClient {
     async get(path, options) {
         // Checked before the path is resolved, and keyed by the path as the caller
         // wrote it, so a cached read needs neither version discovery nor a token.
-        if (options?.ttl && this.cache.has(path)) {
-            log("DEBUG", `Cache hit: ${path}`);
-            return this.cache.get(path);
+        //
+        // The entry has to be younger than this caller's own TTL, not merely
+        // still alive. One path can be written under two TTLs: the discussion
+        // forum list is thirty minutes of course content to get_discussions and
+        // ten minutes of due dates to get_upcoming_due_dates. Trusting the
+        // surviving entry served the longer caller's staleness to the shorter one.
+        if (options?.ttl) {
+            const age = this.cache.ageOf(path);
+            if (age !== undefined && age <= options.ttl) {
+                log("DEBUG", `Cache hit: ${path}`);
+                return this.cache.get(path);
+            }
         }
         const resolved = await this.resolvePath(path);
         const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token));

package/build/api/rate-limiter.js

@@ -25,21 +25,30 @@ export class TokenBucket {
         this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
         this.lastRefill = now;
     }
+    /**
+     * Take `count` tokens, waiting for them if the bucket is short.
+     *
+     * The tokens are deducted before the wait rather than after it, so
+     * concurrent callers queue behind one another. Deducting afterwards let
+     * every caller read the same empty bucket, wait for the same single token,
+     * and then wake together and take it: a fan-out across courses drained the
+     * burst and then admitted the whole remainder one refill later, which is the
+     * 429 storm this limiter exists to prevent. It also left the balance deeply
+     * negative, so the next unrelated request paid the whole debt in one wait.
+     *
+     * A negative balance is that debt, owed by the waiters already queued, and
+     * refill() pays it down at the refill rate.
+     */
     async consume(count = 1) {
         this.refill();
-        if (this.tokens >= count) {
-            // Enough tokens available - consume immediately
-            this.tokens -= count;
+        const shortfall = count - this.tokens;
+        this.tokens -= count;
+        if (shortfall <= 0) {
+            // Enough tokens were already banked - proceed immediately.
             return;
         }
-        // Not enough tokens - calculate wait time
-        const tokensNeeded = count - this.tokens;
-        const waitTimeMs = (tokensNeeded / this.refillRate) * 1000;
-        // Wait for tokens to refill
+        const waitTimeMs = (shortfall / this.refillRate) * 1000;
         await new Promise((resolve) => setTimeout(resolve, waitTimeMs));
-        // Refill and consume
-        this.refill();
-        this.tokens -= count;
     }
     tryConsume(count = 1) {
         this.refill();
@@ -49,8 +58,10 @@ export class TokenBucket {
         }
         return false;
     }
+    /** Tokens free to take right now. Never negative: an outstanding
+     * reservation is a debt, not a negative supply. */
     get availableTokens() {
         this.refill();
-        return this.tokens;
+        return Math.max(0, this.tokens);
     }
 }

package/build/auth/auth-cooldown.js

@@ -24,6 +24,20 @@ export class AuthenticationCooldownError extends Error {
         this.name = "AuthenticationCooldownError";
     }
 }
+/** The recorded retry time, or undefined when the file says nothing usable. */
+function readRetryAt(content) {
+    let status;
+    try {
+        status = JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof status !== "object" || status === null || Array.isArray(status))
+        return undefined;
+    const retryAt = status.retryAt;
+    return typeof retryAt === "number" && Number.isFinite(retryAt) ? retryAt : undefined;
+}
 /** Non-secret retry metadata. Call only while holding the authentication lock. */
 export class AuthCooldown {
     file;
@@ -40,9 +54,19 @@ export class AuthCooldown {
                 return;
             throw error;
         }
-        const status = JSON.parse(content);
-        if (typeof status.retryAt === "number" && status.retryAt > Date.now())
-            throw new AuthenticationCooldownError(status.retryAt);
+        const retryAt = readRetryAt(content);
+        if (retryAt === undefined) {
+            // This file is non-secret retry metadata, and only a readable retryAt is
+            // evidence of anything. A truncated or non-object file used to throw out
+            // of here, which runs before the sign-in attempt — and the automatic path
+            // only clears the file after a sign-in that then never started. One
+            // damaged file disabled background sign-in for good, with nothing on
+            // screen naming the cause. Discard it and let this attempt proceed.
+            await fs.unlink(this.file).catch(() => { });
+            return;
+        }
+        if (retryAt > Date.now())
+            throw new AuthenticationCooldownError(retryAt);
     }
     async recordMfaFailure() {
         await this.write({ retryAt: Date.now() + MFA_COOLDOWN_MS });

package/build/auth/credential-store.js

@@ -178,11 +178,24 @@ function decodeKey(value) {
     }
     return Buffer.from(value, "hex");
 }
+function sessionKeyAccount(canonicalDir) {
+    return `session-key:${createHash("sha256").update(canonicalDir).digest("hex")}`;
+}
+/**
+ * Whether this session directory already holds a native encryption key, which
+ * is what separates an upgrade that has not run yet from one that finished.
+ * A locked or unavailable store raises instead of answering false, so a
+ * caller never mistakes "cannot tell" for "not migrated".
+ */
+export async function hasSessionEncryptionKey(sessionDir, backend = nativeCredentialBackend) {
+    const canonicalDir = await fs.realpath(sessionDir);
+    return (await backend.getPassword(SERVICE, sessionKeyAccount(canonicalDir))) !== null;
+}
 /** The canonical session directory stays stable when DHCP changes the hostname. */
 export async function getSessionEncryptionKey(sessionDir, backend = nativeCredentialBackend, create = true) {
     await fs.mkdir(sessionDir, { recursive: true, mode: 0o700 });
     const canonicalDir = await fs.realpath(sessionDir);
-    const account = `session-key:${createHash("sha256").update(canonicalDir).digest("hex")}`;
+    const account = sessionKeyAccount(canonicalDir);
     const existing = await backend.getPassword(SERVICE, account);
     if (existing !== null) {
         try {

package/build/auth/duo-mfa.js

@@ -1,6 +1,42 @@
 import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { UnsupportedAuthenticationError } from "./sso-flow.js";
+/** Duo's verified-push digits: three to six, per Duo's push-verification policy. */
+const VERIFICATION_CODE_PATTERN = /^\d{3,6}$/;
+/**
+ * Duo renders the verified-push digits in an element of its own. Read that
+ * element rather than the document at large: an unscoped
+ * page.getByText(/^\d{3,6}$/) matches ANY standalone three-to-six digit text on
+ * the page — a masked phone number's last four, a countdown, a "remembered for
+ * 30 days" line — and .first() then announces whichever one the DOM happened to
+ * render first. A headless run has no screen to check that against, so the
+ * wrong number is simply typed into Duo Mobile and the push is denied.
+ */
+const VERIFICATION_CODE_SELECTORS = [
+    ".verification-code",
+    "#verification-code",
+    "[class*='verification-code']",
+];
+/**
+ * Duo's prompt surface, innermost first, bounding the fallback text scan for
+ * the day Duo renames the element above. The first one on screen decides:
+ * numbers rendered outside Duo's own prompt are not the code.
+ */
+const PROMPT_SCOPE_SELECTORS = [
+    "#auth-view",
+    ".base-wrapper",
+    "#root",
+    "#app",
+    "main",
+    "body",
+];
+/** The digits on a visible element, or null when it is absent or not digits. */
+async function readCodeFrom(target) {
+    if (!await target.isVisible().catch(() => false))
+        return null;
+    const code = (await target.textContent().catch(() => null))?.trim();
+    return code && VERIFICATION_CODE_PATTERN.test(code) ? code : null;
+}
 /** Duo Universal Prompt redirects to a Duo-hosted page after primary sign-in. */
 export function isDuoPrompt(page) {
     try {
@@ -40,11 +76,43 @@ export class DuoMfaHandler {
         return true;
     }
     async readVerificationCode(page) {
-        const target = page.getByText(/^\d{3,6}$/).first();
-        if (!await target.isVisible().catch(() => false))
-            return null;
-        const code = (await target.textContent().catch(() => null))?.trim();
-        return code && /^\d{3,6}$/.test(code) ? code : null;
+        return await this.readCodeElement(page) ?? await this.readScopedCode(page);
+    }
+    /** Duo's own verification-code element, when the prompt exposes one. */
+    async readCodeElement(page) {
+        for (const selector of VERIFICATION_CODE_SELECTORS) {
+            const code = await readCodeFrom(page.locator(selector).first());
+            if (code)
+                return code;
+        }
+        return null;
+    }
+    /**
+     * Fallback for a prompt that does not label its digits: the standalone
+     * numbers inside Duo's prompt container. Announce one only when they all
+     * agree — two different numbers mean this is not a screen this can read, and
+     * naming the wrong one costs the user the push.
+     */
+    async readScopedCode(page) {
+        for (const selector of PROMPT_SCOPE_SELECTORS) {
+            const scope = page.locator(selector).first();
+            if (!await scope.isVisible().catch(() => false))
+                continue;
+            const found = [];
+            const candidates = await scope.getByText(VERIFICATION_CODE_PATTERN).all().catch(() => []);
+            for (const candidate of candidates) {
+                // Nested elements repeat the same text; only distinct values compete.
+                const code = await readCodeFrom(candidate);
+                if (code && !found.includes(code))
+                    found.push(code);
+            }
+            if (found.length > 1) {
+                log("DEBUG", `Duo prompt showed ${found.length} standalone numbers; announcing none of them.`);
+                return null;
+            }
+            return found[0] ?? null;
+        }
+        return null;
     }
     async submitPasscode(page) {
         if (this.options.headless === false || this.passcodeSubmitted)
@@ -59,6 +127,13 @@ export class DuoMfaHandler {
         const code = await this.options.requestMfaCode();
         if (!/^\d{6,8}$/.test(code))
             throw new UnsupportedAuthenticationError("The MFA code must contain 6-8 digits.");
+        // That prompt blocks on a person for as long as they take to find the
+        // code, and Duo expires its prompt and redirects on its own schedule. A
+        // passcode is a credential: confirm it is still Duo's page receiving it
+        // rather than whatever the browser moved on to.
+        if (!this.isChallenge(page)) {
+            throw new UnsupportedAuthenticationError(`The Duo prompt closed before the passcode was entered. Run \`${AUTH_COMMAND}\` to retry.`);
+        }
         await input.fill(code);
         const verify = page.getByRole("button", { name: /verify/i }).first();
         if (await verify.isVisible().catch(() => false))

package/build/auth/purdue-sso.js

@@ -113,7 +113,16 @@ export class PurdueSSOFlow {
         if (!this.config.password)
             throw new BrowserAuthError("Password is required for SSO login", "credentials");
         log("INFO", "Entering credentials");
-        if (!this.accountHintSubmitted) {
+        // A submitted account hint only counts once Microsoft has actually left the
+        // email step. It keeps that field on screen whenever it rejects the hint,
+        // and clickWhenReady swallows a click that never landed on purpose (Entra
+        // normally detaches the button after navigating), so identifyAccount can
+        // report a success the page never granted. Skipping the email step there
+        // spends the whole password timeout on a page still asking for a username
+        // and then blames a missing password field.
+        const hintAccepted = this.accountHintSubmitted && !await this.anyVisible(page, EMAIL_SELECTORS);
+        this.accountHintSubmitted = false;
+        if (!hintAccepted) {
             const email = signInName(this.config.username, this.config.baseUrl);
             if (!await this.fillWhenReady(page, EMAIL_SELECTORS, email)) {
                 throw new UnsupportedAuthenticationError("The Microsoft email field did not appear. Automatic sign-in cannot continue.");
@@ -122,7 +131,6 @@ export class PurdueSSOFlow {
                 throw new UnsupportedAuthenticationError("The Microsoft email submit button did not appear. Automatic sign-in cannot continue.");
             }
         }
-        this.accountHintSubmitted = false;
         if (!await this.fillWhenReady(page, PASSWORD_SELECTORS, this.config.password)) {
             throw new UnsupportedAuthenticationError("The Microsoft password field did not appear. Automatic sign-in cannot continue.");
         }

package/build/auth/session-store.js

@@ -9,7 +9,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { SessionStoreError } from "../utils/errors.js";
 import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
-import { NativeCredentialStoreError } from "./credential-store.js";
+import { hasSessionEncryptionKey, NativeCredentialStoreError } from "./credential-store.js";
 import { decrypt, readEncryptedRecord, saveEncryptedRecord, trashFile } from "./encrypted-store.js";
 const DEFAULT_SESSION_DIR = path.join(os.homedir(), ".d2l-session");
 function validTenantOrigin(origin) {
@@ -107,10 +107,27 @@ export class SessionStore {
             throw new Error("Invalid saved session contents.");
         return token;
     }
+    /**
+     * A version 1 record is sealed with scrypt over the local account name and
+     * an on-disk salt: material every local process already has, so the record
+     * proves nothing about who wrote it. It is worth trusting only during the
+     * one-time upgrade, which by definition happens before this directory owns
+     * a native key. Once the key exists the upgrade has already run, and a
+     * version 1 file can only have been planted by something that could write
+     * the session directory but could not reach the credential store. Refuse it
+     * rather than let it replace the authenticated session.
+     */
+    async assertLegacyUpgradePending() {
+        if (!await hasSessionEncryptionKey(this.sessionDir, this.options.backend))
+            return;
+        throw new SessionStoreError("An old unauthenticated session file appeared after this installation was already using native key storage. It was not trusted and was left in place. Sign in again to replace it.");
+    }
     async loadUnlocked() {
         const record = await this.readFile();
         if (!record)
             return null;
+        if (record.version === 1)
+            await this.assertLegacyUpgradePending();
         const token = await this.decode(record);
         if (record.version === 1)
             await this.saveUnlocked(token);
@@ -122,6 +139,10 @@ export class SessionStore {
         await saveEncryptedRecord(this.sessionDir, this.sessionFilePath, "session", token, this.options);
     }
     storeError(action, error) {
+        // A store error already carries the specific reason and the way out of it;
+        // wrapping it again would bury both behind the generic sentence below.
+        if (error instanceof SessionStoreError)
+            throw error;
         if (error instanceof NativeCredentialStoreError || error instanceof AuthenticationInProgressError)
             throw error;
         throw new SessionStoreError(`Failed to ${action} session. Existing session data was preserved.`, error instanceof Error ? error : new Error(String(error)));

package/build/auth/suny-sso.js

@@ -6,6 +6,7 @@
 import { PurdueSSOFlow } from "./purdue-sso.js";
 import { log } from "../utils/logger.js";
 import { UnsupportedAuthenticationError } from "./sso-flow.js";
+import { BrowserAuthError } from "../utils/errors.js";
 /** SUNY campuses share one Brightspace tenant behind one Shibboleth IdP. */
 const SUNY_BRIGHTSPACE_HOST = "mylearning.suny.edu";
 const SUNY_IDP_ENTITY_ID = "https://idm.suny.edu/shibboleth/idp/";
@@ -73,6 +74,12 @@ export class SunySSOFlow {
             await this.selectCampus(page);
         }
         catch (error) {
+            // selectCampus already names the cause and, for a mismatch, lists the
+            // campuses SUNY itself is offering. Re-wrapping those threw away the
+            // only list a user can act on, so pass an already-typed failure through
+            // and describe only the ones that arrive untyped.
+            if (error instanceof BrowserAuthError)
+                throw error;
             throw new UnsupportedAuthenticationError("SUNY campus selection could not complete automatically. Run brightspace-mcp-server setup --suny and select a campus.", error);
         }
         return this.defaultFlow.login(page);

package/build/index.js

@@ -16,7 +16,7 @@ import { startUpdateChecks } from "./utils/update-checker.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_VERSION = (() => {
@@ -113,11 +113,12 @@ else {
             registerGetSyllabus(server, apiClient);
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
-            log("DEBUG", "MCP tools registered (13 tools)");
+            registerGetServerInfo(server, config, PKG_VERSION);
+            log("DEBUG", "MCP tools registered (14 tools)");
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (13 tools registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (14 tools registered)");
             log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
         }
         catch (error) {

package/build/setup.js

@@ -14,6 +14,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { configStoreExists, getConfigStorePath, loadConfigStore, } from "./utils/config-store.js";
 import { saveSecureConfig } from "./utils/secure-config.js";
+import { writeFileAtomicSync } from "./utils/atomic-write.js";
 import { AUTH_COMMAND } from "./utils/commands.js";
 import { cliMcpClients, configureCliMcpClient, isCliAvailable, } from "./utils/mcp-client-cli.js";
 // ANSI helpers
@@ -22,7 +23,7 @@ const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
-const SCHOOL_PRESETS = {
+export const SCHOOL_PRESETS = {
     purdue: {
         name: "Purdue University",
         baseUrl: "https://purdue.brightspace.com",
@@ -45,9 +46,20 @@ const SCHOOL_PRESETS = {
         usernameHint: "Use your full sign-in address if your Western account requires it.",
     },
 };
-// Parse --purdue, --osu, etc. from argv
-const schoolFlag = process.argv.find((a) => a.startsWith("--"))?.replace(/^--/, "").toLowerCase();
-const preset = schoolFlag ? SCHOOL_PRESETS[schoolFlag] : undefined;
+/**
+ * Pick the school preset named by `--purdue`, `--suny`, `--western`, etc.
+ *
+ * Own properties only: a bare index would make `--constructor` or
+ * `--__proto__` resolve to something off `Object.prototype` and hand the
+ * wizard an object with no `baseUrl`.
+ */
+export function presetForArgv(argv = process.argv) {
+    const flag = argv.find((a) => a.startsWith("--"))?.replace(/^--/, "").toLowerCase();
+    if (!flag || !Object.prototype.hasOwnProperty.call(SCHOOL_PRESETS, flag))
+        return undefined;
+    return SCHOOL_PRESETS[flag];
+}
+const preset = presetForArgv();
 // ── Readline helpers ───────────────────────────────────────────────
 function ask(rl, question) {
     return new Promise((resolve) => {
@@ -174,27 +186,45 @@ function isChatGPTInstalled() {
 function getCursorConfigPath() {
     return path.join(os.homedir(), ".cursor", "mcp.json");
 }
-function configureMcpClient(configPath) {
-    let config = { mcpServers: {} };
+/**
+ * A JSON value we can safely merge a server entry into. An array passes
+ * `typeof x === "object"` but drops every added key when it is stringified
+ * again, so it has to be rejected alongside `null`.
+ */
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function configureMcpClient(configPath) {
+    let config = {};
     // Read existing config if present
     if (fs.existsSync(configPath)) {
+        let parsed;
+        let readable = true;
         try {
-            const raw = fs.readFileSync(configPath, "utf-8");
-            config = JSON.parse(raw);
+            parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
         }
         catch {
-            // If we can't parse, start fresh but warn
-            console.log(yellow("  Warning: existing config was invalid, creating new one."));
-            config = { mcpServers: {} };
+            readable = false;
+        }
+        if (isJsonObject(parsed)) {
+            config = parsed;
+        }
+        else {
+            // Unparseable, or valid JSON that is not an object (null, an array, a
+            // bare string). Merging into it would either throw or silently discard
+            // the entry we just reported as written, so start fresh and say so.
+            console.log(yellow(`  Warning: existing config was ${readable ? "not a JSON object" : "invalid"}, creating new one.`));
+            config = {};
         }
     }
-    if (!config.mcpServers) {
-        config.mcpServers = {};
-    }
+    // Same reasoning for the servers map itself, which is hand-edited far more
+    // often than the file around it.
+    const servers = isJsonObject(config.mcpServers) ? config.mcpServers : {};
+    config.mcpServers = servers;
     // Add/update brightspace entry
     // On Windows, npx is a .cmd shim that must be invoked through cmd.exe
     const isWindows = process.platform === "win32";
-    config.mcpServers["brightspace"] = isWindows
+    servers["brightspace"] = isWindows
         ? {
             command: "cmd",
             args: ["/c", "npx", "-y", "brightspace-mcp-server@latest"],
@@ -208,9 +238,73 @@ function configureMcpClient(configPath) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+    // This file holds every MCP server the user has configured, not just ours.
+    // A plain write truncates it first, so a write that fails part way through
+    // (a full disk, an I/O error) would leave the user with no MCP servers at
+    // all. Staging and renaming leaves either the old file or the new one.
+    // The existing permissions are carried over, since the rename would
+    // otherwise replace them with the umask default.
+    let mode;
+    try {
+        if (fs.existsSync(configPath))
+            mode = fs.statSync(configPath).mode & 0o777;
+    }
+    catch {
+        // Unreadable metadata is not a reason to skip the write.
+    }
+    writeFileAtomicSync(configPath, JSON.stringify(config, null, 2) + "\n", mode === undefined ? {} : { mode });
     return true;
 }
+/** The settings already on disk, or null when there are none to read. */
+export function readExistingConfig() {
+    try {
+        return configStoreExists() ? loadConfigStore() : null;
+    }
+    catch {
+        // An unreadable config is replaced by the setup values.
+        return null;
+    }
+}
+function sameSchool(stored, chosen) {
+    // A config that never recorded a school (environment-driven installs) is
+    // not a *different* school, so its settings are still ours to keep.
+    if (!stored)
+        return true;
+    try {
+        return new URL(stored).origin === new URL(chosen).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Merge the wizard's answers over the settings already saved.
+ *
+ * `saveConfigStore` replaces the whole file, and setup is the documented way
+ * to update a saved password — so it runs again on configurations that carry
+ * settings it never prompts for: the SUNY campus, course filters, a custom
+ * session directory or token TTL. Writing only the answers deleted all of
+ * them; most visibly, a SUNY user who reran plain `setup` lost the campus
+ * that lets sign-in skip the shared campus picker.
+ *
+ * Settings are carried only within one school, since course ids and the
+ * campus belong to a single tenant.
+ */
+export function buildConfigToSave(existing, answers) {
+    const carried = existing && sameSchool(existing.baseUrl, answers.baseUrl) ? existing : null;
+    const config = {
+        ...carried,
+        baseUrl: answers.baseUrl,
+        username: answers.username,
+        // Always the freshly typed one: a carried v1 plaintext password would
+        // otherwise be the value written to the native store.
+        password: answers.password,
+        headless: answers.headless,
+    };
+    if (answers.campus)
+        config.campus = answers.campus;
+    return config;
+}
 // ── Auth spawn ─────────────────────────────────────────────────────
 function runAuth() {
     const scriptPath = path.resolve(thisDir, "auth-cli.js");
@@ -349,15 +443,13 @@ async function main() {
         : "  A browser window will open when authentication is needed."));
     console.log("");
     // ── Step 5: Save config ──────────────────────────────────────────
-    const config = {
+    const config = buildConfigToSave(readExistingConfig(), {
         baseUrl,
         username,
         password,
         headless,
-    };
-    if (campus) {
-        config.campus = campus;
-    }
+        campus: campus || undefined,
+    });
     await saveSecureConfig(config);
     console.log(green("  Password saved in your operating system credential store."));
     console.log(green("  Config saved to: " + getConfigStorePath()));
@@ -467,7 +559,13 @@ async function main() {
     }
     console.log("");
 }
-main().catch((err) => {
-    console.error("Setup failed:", err instanceof Error ? err.message : String(err));
-    process.exit(1);
-});
+// Both entry points — the `brightspace-setup` bin and `brightspace-mcp-server
+// setup`, which imports this module — start the wizard here. VITEST is set
+// only by the test runner, which imports the module for the helpers above and
+// must not open prompts on stdin; no user environment sets it.
+if (!process.env.VITEST) {
+    main().catch((err) => {
+        console.error("Setup failed:", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}