brightspace-mcp-server 3.15.4 → 4.0.1

package/build/setup.js

@@ -5,104 +5,44 @@
  * Licensed under MIT — see LICENSE file for details.
  *
  * https://github.com/rohanmuppa/brightspace-mcp-server
+ *
+ * `setup`, in three modes (see src/setup/args.ts): the interactive wizard,
+ * `--prepare` for an AI agent (src/setup/prepare.ts, no prompts), and
+ * `--sign-in`, the person's last step after prepare.
  */
 import * as readline from "node:readline";
-import * as fs from "node:fs";
 import * as path from "node:path";
-import * as os from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { configStoreExists, getConfigStorePath, loadConfigStore, } from "./utils/config-store.js";
+import { getConfigStorePath } from "./utils/config-store.js";
 import { saveSecureConfig } from "./utils/secure-config.js";
-import { deleteStoredTotpUri, getStoredTotpUri } from "./auth/credential-store.js";
+import { deleteStoredTotpUri, getStoredPassword, getStoredTotpUri } from "./auth/credential-store.js";
 import { askShortcutQuestion } from "./utils/two-factor-shortcuts.js";
-import { writeFileAtomicSync } from "./utils/atomic-write.js";
-import { AUTH_COMMAND, DOCTOR_COMMAND } from "./utils/commands.js";
-import { classifyRegistration, cliMcpClients, inspectCliMcpClient, isCliAvailable, registerCliMcpClient, serverCommand, } from "./utils/mcp-client-cli.js";
+import { DOCTOR_COMMAND, prepareCommand, signInCommand } from "./utils/commands.js";
+import { serverCommand } from "./utils/mcp-client-cli.js";
+import { parseSetupArgs, SETUP_USAGE } from "./setup/args.js";
+import { buildConfigToSave, isValidUrl, normalizeUrl, readExistingConfig, sameSchool } from "./setup/config.js";
+import { detectMcpClients, isChatGPTInstalled } from "./setup/clients.js";
+import { presetForBaseUrl } from "./setup/presets.js";
+import { formatPrepare, runPrepare } from "./setup/prepare.js";
+// Kept importable from here for existing callers and tests.
+export { SCHOOL_PRESETS } from "./setup/presets.js";
+export { buildConfigToSave, readExistingConfig } from "./setup/config.js";
+export { configureMcpClient, inspectMcpClient } from "./setup/clients.js";
 // ANSI helpers
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 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));
-export const SCHOOL_PRESETS = {
-    tudelft: {
-        name: "TU Delft",
-        baseUrl: "https://brightspace.tudelft.nl",
-        usernameLabel: "TU Delft NetID",
-        mfaNote: "NetID sign-in normally runs headlessly without MFA.",
-        usernameHint: "Use your NetID, not your student email address.",
-    },
-    leiden: {
-        name: "Leiden University",
-        baseUrl: "https://brightspace.universiteitleiden.nl",
-        usernameLabel: "Leiden University username",
-        mfaNote: "Leiden usually asks for a code from your authenticator app, which you can type here.",
-        usernameHint: "Use the full address you sign in to Microsoft with, e.g. s1234567@vuw.leidenuniv.nl.",
-    },
-    purdue: {
-        name: "Purdue University",
-        baseUrl: "https://purdue.brightspace.com",
-        usernameLabel: "Purdue career account username or full email",
-        mfaNote: "Microsoft Authenticator number matching can run without a browser window.",
-    },
-    suny: {
-        name: "SUNY",
-        baseUrl: "https://mylearning.suny.edu",
-        usernameLabel: "SUNY campus username",
-        mfaNote: "Approve the sign-in request from your campus MFA app.",
-        campusPrompt: "Which SUNY campus are you at? (e.g. SUNY Poly)",
-        usernameHint: "Most campuses want the full sign-in address, e.g. abc123@sunypoly.edu",
-    },
-    western: {
-        name: "Western University",
-        baseUrl: "https://westernu.brightspace.com",
-        usernameLabel: "Western account username or full email",
-        mfaNote: "Approve the sign-in request from your MFA app.",
-        usernameHint: "Use your full sign-in address if your Western account requires it.",
-    },
-    cuny: {
-        name: "CUNY",
-        baseUrl: "https://brightspace.cuny.edu",
-        usernameLabel: "CUNY Login username",
-        mfaNote: "Type the 6-digit code from your authenticator app when prompted.",
-        usernameHint: "Use your full CUNY Login address, e.g. firstname.lastname01@login.cuny.edu",
-    },
-    ngeeann: {
-        name: "Ngee Ann Polytechnic",
-        baseUrl: "https://nplms.polite.edu.sg",
-        usernameLabel: "Ngee Ann Polytechnic account username or full email",
-        mfaNote: "Approve the sign-in request from your MFA app.",
-        usernameHint: "Use your full sign-in address if your Ngee Ann Polytechnic account requires it.",
-    },
-    mcgill: {
-        name: "McGill University",
-        baseUrl: "https://mycourses2.mcgill.ca",
-        usernameLabel: "McGill username or full email",
-        mfaNote: "Approve the sign-in request from your MFA app.",
-        usernameHint: "Use your full sign-in address if your McGill account requires it.",
-    },
-    javeriana: {
-        name: "Pontificia Universidad Javeriana Cali",
-        baseUrl: "https://auladigital.javerianacali.edu.co",
-        usernameLabel: "Javeriana username",
-        mfaNote: "OneGate asks for a code from your authenticator app when you sign in.",
-    },
-};
 /**
- * Pick the school preset named by `--purdue`, `--suny`, `--western`, `--cuny`, `--mcgill`, `--ngeeann`, `--javeriana`, 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`.
+ * The school preset named by a flag such as `--purdue`, anywhere on the
+ * command line. Undefined when there is none or the flags don't parse.
  */
 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 parsed = parseSetupArgs(argv);
+    return parsed.ok ? parsed.args.preset : undefined;
 }
-const preset = presetForArgv();
 // ── Readline helpers ───────────────────────────────────────────────
 function ask(rl, question) {
     return new Promise((resolve) => {
@@ -191,223 +131,54 @@ function askPassword(prompt) {
         process.stdin.on("data", onData);
     });
 }
-// ── URL validation ─────────────────────────────────────────────────
-function normalizeUrl(input) {
-    let url = input.trim();
-    // Strip trailing slashes
-    url = url.replace(/\/+$/, "");
-    // Auto-prepend https://
-    if (!/^https?:\/\//i.test(url)) {
-        url = `https://${url}`;
-    }
-    // Upgrade http:// to https://
-    url = url.replace(/^http:\/\//i, "https://");
-    return url;
-}
-function isValidUrl(url) {
-    try {
-        const parsed = new URL(url);
-        return parsed.protocol === "https:" && !parsed.username && !parsed.password;
-    }
-    catch {
-        return false;
-    }
-}
-function getClaudeDesktopConfigPath() {
-    const platform = os.platform();
-    if (platform === "darwin") {
-        return path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
-    }
-    if (platform === "win32") {
-        const appdata = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
-        return path.join(appdata, "Claude", "claude_desktop_config.json");
-    }
-    if (platform === "linux") {
-        return path.join(os.homedir(), ".config", "Claude", "claude_desktop_config.json");
-    }
-    return null;
-}
-function isChatGPTInstalled() {
-    const platform = os.platform();
-    if (platform === "darwin") {
-        return (fs.existsSync("/Applications/ChatGPT.app") ||
-            fs.existsSync(path.join(os.homedir(), "Applications", "ChatGPT.app")));
-    }
-    if (platform === "win32") {
-        const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
-        return fs.existsSync(path.join(localAppData, "Programs", "ChatGPT", "ChatGPT.exe"));
-    }
-    return false;
-}
-function getCursorConfigPath() {
-    return path.join(os.homedir(), ".cursor", "mcp.json");
-}
-function getAntigravityConfigPath() {
-    return path.join(os.homedir(), ".gemini", "antigravity", "mcp_config.json");
-}
-/**
- * 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);
-}
-/** How the client's existing "brightspace" entry compares with ours. */
-export function inspectMcpClient(configPath) {
-    let config;
-    try {
-        config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-    }
-    catch {
-        // No file, or one configureMcpClient would replace anyway.
-        return { state: "missing" };
-    }
-    const servers = isJsonObject(config) ? config.mcpServers : undefined;
-    return classifyRegistration(isJsonObject(servers) ? servers.brightspace : undefined);
-}
-export function configureMcpClient(configPath) {
-    let config = {};
-    // Read existing config if present
-    if (fs.existsSync(configPath)) {
-        let parsed;
-        let readable = true;
-        try {
-            parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        }
-        catch {
-            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 = {};
-        }
-    }
-    // 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
-    const [command, ...args] = serverCommand();
-    servers["brightspace"] = { command, args };
-    // Ensure parent directory exists
-    const dir = path.dirname(configPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    // 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.
+ * The wizard asks everything, as it always has. Sign-in mode runs after
+ * `--prepare`, so it asks only what prepare couldn't know: the password (or
+ * whether to keep a saved one), and the username or campus if the agent
+ * didn't pass them. Registering apps was prepare's job.
  */
-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,
-        // Only ever the freshly typed one. Never read back out of `carried`: the
-        // enrollment lives in the credential store, never in config.json, so a
-        // value here could only have come from this run.
-        ...(answers.totpUri ? { totpUri: answers.totpUri } : {}),
-        headless: answers.headless,
+export function planQuestions(mode, known) {
+    const signIn = mode === "sign-in";
+    return {
+        askUrl: !known.baseUrl,
+        askCampus: known.campusNeeded && !known.campus,
+        askUsername: !known.username,
+        password: signIn && known.passwordSaved ? "keep-or-ask" : "ask",
+        registerApps: !signIn,
+        confirmSignIn: !signIn,
     };
-    if (answers.rememberMfa !== undefined)
-        config.rememberMfa = answers.rememberMfa;
-    // Setup no longer offers passwordless sign-in and always saves a password,
-    // so a carried `passwordless: true` would make sign-in ignore that password.
-    // D2L_PASSWORDLESS still turns it on for anyone who wants it.
-    delete config.passwordless;
-    if (answers.campus)
-        config.campus = answers.campus;
-    return config;
 }
-// ── Auth spawn ─────────────────────────────────────────────────────
+// ── Registering with one app ───────────────────────────────────────
 /**
- * Registers Brightspace in one client, never silently replacing an entry
+ * Registers Brightspace in one app, never silently replacing an entry
  * that points somewhere else: a matching entry is left alone, and a different
  * one is printed (so it can be restored) and replaced only on a yes.
- * Resolves true when the client ends up running the expected entry.
+ * Resolves true when the app ends up running the expected entry.
  */
-async function registerWithClient(rl, displayName, existing, write) {
+async function registerWithClient(rl, target) {
+    const existing = target.inspect();
     if (existing.state === "current") {
-        console.log(green(`  ${displayName} already has Brightspace configured.`));
+        console.log(green(`  ${target.name} already has Brightspace configured.`));
         return true;
     }
     if (existing.state === "different") {
-        console.log(yellow(`  ${displayName} has "brightspace" pointing at:`));
+        console.log(yellow(`  ${target.name} has "brightspace" pointing at:`));
         console.log(`    ${existing.current}`);
         const replace = await ask(rl, `  Replace it with ${serverCommand().join(" ")}? (yes/no): `);
         if (!/^y(es)?$/i.test(replace)) {
-            console.log(dim(`  Left ${displayName} unchanged.`));
+            console.log(dim(`  Left ${target.name} unchanged.`));
             return false;
         }
     }
     try {
-        if (write(existing.state === "different")) {
-            console.log(green(`  ${displayName} configured!`));
+        if (target.write(existing.state === "different")) {
+            console.log(green(`  ${target.name} configured!`));
             return true;
         }
-        console.log(yellow(`  Could not configure ${displayName}. See README.md for the manual command.`));
+        console.log(yellow(`  Could not configure ${target.name}. See README.md for the manual command.`));
     }
     catch (err) {
-        console.log(yellow(`  Could not configure ${displayName}: ${err instanceof Error ? err.message : String(err)}`));
+        console.log(yellow(`  Could not configure ${target.name}: ${err instanceof Error ? err.message : String(err)}`));
     }
     return false;
 }
@@ -422,22 +193,90 @@ function runAuth() {
         child.once("close", (code) => resolve(code === 0));
     });
 }
-// ── Main wizard ────────────────────────────────────────────────────
-async function main() {
+function printChatGPTInstructions() {
+    if (!isChatGPTInstalled())
+        return;
+    const isWindows = process.platform === "win32";
+    const mcpJson = isWindows
+        ? `{\n  "command": "cmd",\n  "args": ["/c", "npx", "-y", "brightspace-mcp-server@latest"]\n}`
+        : `{\n  "command": "npx",\n  "args": ["-y", "brightspace-mcp-server@latest"]\n}`;
+    console.log(yellow("  ChatGPT Desktop detected."));
+    console.log(dim("  ChatGPT doesn't support automatic MCP config — add it manually:"));
+    console.log(dim("  1. Open ChatGPT Desktop → Settings → Tools → Add MCP tool → Add manually"));
+    console.log(dim("  2. Paste this config:"));
+    console.log("");
+    console.log(mcpJson);
+    console.log("");
+}
+// ── Prepare (no prompts) ───────────────────────────────────────────
+async function prepare(args) {
+    const result = await runPrepare(args);
+    const lines = formatPrepare(result);
+    if (args.json) {
+        // stdout carries only the JSON an agent parses.
+        for (const line of lines)
+            console.error(line);
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        for (const line of lines)
+            console.log(line);
+    }
+    process.exitCode = result.state === "ready_for_sign_in" || result.state === "signed_in" ? 0 : 1;
+}
+// ── Wizard and sign-in (interactive) ───────────────────────────────
+async function interactive(args) {
+    const mode = args.mode === "sign-in" ? "sign-in" : "wizard";
     // Handle Ctrl+C gracefully
     process.on("SIGINT", () => {
         console.log("\n\nSetup cancelled.");
         process.exit(0);
     });
-    console.log("");
-    if (preset) {
-        console.log(bold(`Brightspace MCP Server — ${preset.name} Setup`));
-        console.log("=".repeat(`Brightspace MCP Server — ${preset.name} Setup`.length));
+    const saved = readExistingConfig();
+    // ── School ───────────────────────────────────────────────────────
+    let baseUrl = args.preset?.baseUrl;
+    if (!baseUrl && args.url) {
+        const normalized = normalizeUrl(args.url);
+        if (!isValidUrl(normalized)) {
+            console.error(`"${args.url}" isn't a valid Brightspace address. Pass it like --url purdue.brightspace.com`);
+            process.exitCode = 2;
+            return;
+        }
+        baseUrl = new URL(normalized).origin;
     }
-    else {
-        console.log(bold("Brightspace MCP Server — Setup Wizard"));
-        console.log("======================================");
+    if (!baseUrl && mode === "sign-in") {
+        if (!saved?.baseUrl) {
+            console.error(`No school is saved yet. Run ${prepareCommand()} with your school's flag first, or pass the flag here.`);
+            process.exitCode = 2;
+            return;
+        }
+        baseUrl = saved.baseUrl;
     }
+    let preset = args.preset ?? (baseUrl ? presetForBaseUrl(baseUrl)?.preset : undefined);
+    const carried = baseUrl && saved && sameSchool(saved.baseUrl, baseUrl) ? saved : null;
+    const knownUsername = args.username ?? (mode === "sign-in" ? carried?.username : undefined);
+    let passwordSaved = false;
+    if (mode === "sign-in" && baseUrl && knownUsername) {
+        try {
+            passwordSaved = Boolean(await getStoredPassword(baseUrl, knownUsername));
+        }
+        catch {
+            // A locked store: ask for the password, and saving it reports the problem.
+        }
+    }
+    const plan = planQuestions(mode, {
+        baseUrl,
+        campusNeeded: Boolean(preset?.campusPrompt),
+        campus: args.campus ?? (mode === "sign-in" ? carried?.campus : undefined),
+        username: knownUsername,
+        passwordSaved,
+    });
+    console.log("");
+    const title = mode === "sign-in"
+        ? `Brightspace MCP Server — ${preset ? `${preset.name} ` : ""}Sign-in`
+        : preset ? `Brightspace MCP Server — ${preset.name} Setup` : "Brightspace MCP Server — Setup Wizard";
+    console.log(bold(title));
+    console.log("=".repeat(title.length));
     console.log(dim("  By Rohan Muppa — github.com/rohanmuppa/brightspace-mcp-server"));
     console.log("");
     // An assistant often opens this wizard in a side panel the user has never
@@ -449,9 +288,7 @@ async function main() {
         output: process.stdout,
     });
     // ── Step 1: Brightspace URL ──────────────────────────────────────
-    let baseUrl = "";
-    if (preset) {
-        baseUrl = preset.baseUrl;
+    if (!plan.askUrl && baseUrl) {
         console.log(dim(`  Brightspace URL: ${baseUrl}`));
         console.log("");
     }
@@ -466,56 +303,68 @@ async function main() {
             }
             baseUrl = normalized;
         }
+        preset ??= presetForBaseUrl(baseUrl)?.preset;
         console.log(dim(`  → ${baseUrl}`));
         console.log("");
     }
     // ── Campus (shared multi-campus instances only) ──────────────────
-    let campus = "";
-    if (preset?.campusPrompt) {
+    let campus = args.campus ?? (mode === "sign-in" ? carried?.campus ?? "" : "");
+    if (plan.askCampus && preset?.campusPrompt) {
         console.log(dim("  Several campuses share this Brightspace site."));
         while (!campus) {
             campus = await ask(rl, `${preset.campusPrompt} `);
             if (!campus)
                 console.log(yellow("  Campus is required for automatic sign-in."));
         }
-        console.log(campus
-            ? dim(`  → ${campus}`)
-            : dim("  Set your campus before authenticating."));
+        console.log(dim(`  → ${campus}`));
         console.log("");
     }
     // ── Step 2: Username ─────────────────────────────────────────────
-    const usernamePrompt = preset
-        ? `What is your ${preset.usernameLabel}? `
-        : "What username do you use to sign in to Brightspace? ";
-    if (preset?.usernameHint) {
-        console.log(dim(`  ${preset.usernameHint}`));
+    let username = knownUsername ?? "";
+    if (plan.askUsername) {
+        const usernamePrompt = preset
+            ? `What is your ${preset.usernameLabel}? `
+            : "What username do you use to sign in to Brightspace? ";
+        if (preset?.usernameHint) {
+            console.log(dim(`  ${preset.usernameHint}`));
+        }
+        else {
+            console.log(dim("  The same username you type on your school's Brightspace sign-in page."));
+        }
+        while (!username) {
+            username = await ask(rl, usernamePrompt);
+            if (!username) {
+                console.log(yellow("  Username is required."));
+            }
+        }
     }
     else {
-        console.log(dim("  The same username you type on your school's Brightspace sign-in page."));
-    }
-    let username = "";
-    while (!username) {
-        username = await ask(rl, usernamePrompt);
-        if (!username) {
-            console.log(yellow("  Username is required."));
-        }
+        console.log(dim(`  Username: ${username}`));
     }
     console.log("");
     // ── Step 3: Password (hidden) ────────────────────────────────────
+    let keepPassword = false;
+    if (plan.password === "keep-or-ask") {
+        const answer = await ask(rl, `  A password is already saved for ${username}. Keep it? (yes/no) [yes]: `);
+        keepPassword = !answer || /^y(es)?$/i.test(answer);
+        console.log("");
+    }
     // Close the rl temporarily since askPassword manages its own
     rl.close();
     let password = "";
-    console.log(dim("  The password you use to sign in. It won't be shown as you type — asterisks stand in for each character."));
-    const passwordPrompt = preset
-        ? `What is your ${preset.name} password? `
-        : "What is your Brightspace password? ";
-    while (!password) {
-        password = await askPassword(passwordPrompt);
-        if (!password) {
-            console.log(yellow("  Password is required."));
+    if (!keepPassword) {
+        console.log(dim("  The password you use to sign in. It won't be shown as you type — asterisks stand in for each character."));
+        const passwordPrompt = preset
+            ? `What is your ${preset.name} password? `
+            : "What is your Brightspace password? ";
+        while (!password) {
+            password = await askPassword(passwordPrompt);
+            if (!password) {
+                console.log(yellow("  Password is required."));
+            }
         }
+        console.log("");
     }
-    console.log("");
     // Re-open readline for remaining prompts
     let rl2 = readline.createInterface({
         input: process.stdin,
@@ -538,16 +387,8 @@ async function main() {
     console.log("  How do you confirm it's you when you sign in?");
     console.log("    1. With a phone app: I tap Approve or type a code (recommended)");
     console.log("    2. Another way, like a text message: show me the sign-in page");
-    let savedHeadless;
-    let savedRememberMfa;
-    try {
-        const saved = configStoreExists() ? loadConfigStore() : undefined;
-        savedHeadless = saved?.headless;
-        savedRememberMfa = saved?.rememberMfa;
-    }
-    catch {
-        // An invalid old config is replaced by the setup values below.
-    }
+    const savedHeadless = saved?.headless;
+    const savedRememberMfa = saved?.rememberMfa;
     const defaultMfaChoice = savedHeadless === false ? "2" : "1";
     let mfaChoice = "";
     while (!/^[12]$/.test(mfaChoice)) {
@@ -599,14 +440,17 @@ async function main() {
     const config = buildConfigToSave(readExistingConfig(), {
         baseUrl,
         username,
-        password,
+        // Undefined when the saved one is kept: the credential store is left alone.
+        password: password || undefined,
         totpUri,
         headless,
         rememberMfa,
         campus: campus || undefined,
     });
     await saveSecureConfig(config);
-    console.log(green("  Password saved in your operating system credential store."));
+    console.log(green(keepPassword
+        ? "  Kept the password already saved in your operating system credential store."
+        : "  Password saved in your operating system credential store."));
     if (totpUri)
         console.log(green("  Authenticator enrollment saved in your operating system credential store."));
     if (shortcuts?.removeKey) {
@@ -620,90 +464,60 @@ async function main() {
     }
     console.log(green("  Config saved to: " + getConfigStorePath()));
     console.log("");
-    // ── Step 6: Authenticate now? ────────────────────────────────────
-    const authNow = await ask(rl2, "Sign in now, so everything is ready to go? (yes/no): ");
-    if (/^y(es)?$/i.test(authNow)) {
-        rl2.close();
+    // ── Step 6: AI apps ──────────────────────────────────────────────
+    // Before signing in, so someone who stops at the approval step still has
+    // the server registered, and the next question in their AI app signs in.
+    if (plan.registerApps) {
+        for (const target of detectMcpClients()) {
+            const answer = await ask(rl2, target.question);
+            if (/^y(es)?$/i.test(answer) && await registerWithClient(rl2, target)) {
+                configuredClients.push(target.name);
+            }
+            console.log("");
+        }
+        printChatGPTInstructions();
+    }
+    // ── Step 7: Sign in ──────────────────────────────────────────────
+    const retry = signInCommand(baseUrl);
+    let signInNow = true;
+    if (plan.confirmSignIn) {
+        const authNow = await ask(rl2, "Sign in now, so everything is ready to go? (yes/no): ");
+        signInNow = /^y(es)?$/i.test(authNow);
+    }
+    rl2.close();
+    let signedIn = false;
+    if (signInNow) {
         console.log("");
         console.log(dim("  Signing you in..."));
         console.log("");
-        const ok = await runAuth();
-        rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
-        if (ok) {
+        signedIn = await runAuth();
+        if (signedIn) {
             console.log(green("\n  Signed in!"));
         }
         else {
-            console.log(yellow(`\n  Sign-in didn't finish. You can try again later by running: ${AUTH_COMMAND}`));
+            console.log(yellow(`\n  Sign-in didn't finish. To try again, run: ${retry}`));
         }
     }
     else {
-        console.log(dim(`  You can sign in later by running: ${AUTH_COMMAND}`));
+        console.log(dim(`  You can sign in later by running: ${retry}`));
     }
     console.log("");
-    // ── Step 7: Claude Desktop auto-config ───────────────────────────
-    const claudePath = getClaudeDesktopConfigPath();
-    if (claudePath) {
-        const configClaude = await ask(rl2, "Would you like to automatically configure Claude Desktop? Highly recommended. (yes/no): ");
-        if (/^y(es)?$/i.test(configClaude) &&
-            await registerWithClient(rl2, "Claude Desktop", inspectMcpClient(claudePath), () => configureMcpClient(claudePath))) {
-            configuredClients.push("Claude Desktop");
-        }
-        console.log("");
-    }
-    // ── Step 8: Cursor auto-config ───────────────────────────────────
-    const cursorPath = getCursorConfigPath();
-    const cursorExists = fs.existsSync(path.dirname(cursorPath));
-    if (cursorExists) {
-        const configCursor = await ask(rl2, "Cursor detected. Would you like to configure it too? (yes/no): ");
-        if (/^y(es)?$/i.test(configCursor) &&
-            await registerWithClient(rl2, "Cursor", inspectMcpClient(cursorPath), () => configureMcpClient(cursorPath))) {
-            configuredClients.push("Cursor");
-        }
-        console.log("");
-    }
-    // ── Antigravity auto-config ──────────────────────────────────────
-    const antigravityPath = getAntigravityConfigPath();
-    if (fs.existsSync(path.dirname(antigravityPath))) {
-        const configAntigravity = await ask(rl2, "Antigravity detected. Would you like to configure it too? (yes/no): ");
-        if (/^y(es)?$/i.test(configAntigravity) &&
-            await registerWithClient(rl2, "Antigravity", inspectMcpClient(antigravityPath), () => configureMcpClient(antigravityPath))) {
-            configuredClients.push("Antigravity");
-        }
-        console.log("");
-    }
-    // ── Step 9: Codex and Claude Code auto-config ─────────────────────
-    for (const client of cliMcpClients()) {
-        if (!isCliAvailable(client))
-            continue;
-        const configureClient = await ask(rl2, `${client.displayName} detected. Configure it automatically? Highly recommended. (yes/no): `);
-        if (/^y(es)?$/i.test(configureClient) &&
-            await registerWithClient(rl2, client.displayName, inspectCliMcpClient(client), (replace) => registerCliMcpClient(client, { replace }))) {
-            configuredClients.push(client.displayName);
-        }
-        console.log("");
-    }
-    // ── Step 10: ChatGPT Desktop instructions ────────────────────────
-    if (isChatGPTInstalled()) {
-        const isWindows = process.platform === "win32";
-        const mcpJson = isWindows
-            ? `{\n  "command": "cmd",\n  "args": ["/c", "npx", "-y", "brightspace-mcp-server@latest"]\n}`
-            : `{\n  "command": "npx",\n  "args": ["-y", "brightspace-mcp-server@latest"]\n}`;
-        console.log(yellow("  ChatGPT Desktop detected."));
-        console.log(dim("  ChatGPT doesn't support automatic MCP config — add it manually:"));
-        console.log(dim("  1. Open ChatGPT Desktop → Settings → Tools → Add MCP tool → Add manually"));
-        console.log(dim("  2. Paste this config:"));
-        console.log("");
-        console.log(mcpJson);
-        console.log("");
+    // Sign-in mode exists to sign in, so it reports done only once that worked.
+    if (mode === "sign-in" && !signedIn) {
+        process.exitCode = 1;
+        return;
     }
-    rl2.close();
     // ── Final summary ────────────────────────────────────────────────
     console.log(bold("Setup complete!"));
     console.log("");
     console.log(`  Config saved to: ${dim(getConfigStorePath())}`);
     console.log("");
     console.log("  Next steps:");
-    if (configuredClients.length > 0) {
+    if (mode === "sign-in") {
+        console.log("  1. Go back to your AI app. If it was open while setup ran, restart it.");
+        console.log(`  2. Ask it: "What's due this week?"`);
+    }
+    else if (configuredClients.length > 0) {
         console.log(`  1. Restart ${configuredClients.join(", ")}`);
         console.log(`  2. Ask it: "What's due this week?"`);
         console.log("     Sign-in runs automatically if your saved session has expired.");
@@ -716,10 +530,39 @@ async function main() {
     console.log(dim(`  If something doesn't work, run: ${DOCTOR_COMMAND}`));
     console.log("");
 }
+async function main() {
+    const parsed = parseSetupArgs();
+    if (!parsed.ok) {
+        console.error(parsed.error);
+        console.error("");
+        console.error(SETUP_USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    const args = parsed.args;
+    if (args.help) {
+        console.log(SETUP_USAGE);
+        return;
+    }
+    if (args.mode === "prepare") {
+        await prepare(args);
+        return;
+    }
+    // The wizard and sign-in wait for typing. Without a terminal (an agent's
+    // shell, a pipe) they would hang, so say what to run instead.
+    if (!process.stdin.isTTY) {
+        console.error("Setup asks questions, so it has to run in a terminal someone can type in.");
+        const school = args.preset?.baseUrl ?? (args.url && isValidUrl(normalizeUrl(args.url)) ? normalizeUrl(args.url) : undefined);
+        console.error(`An AI agent should run ${prepareCommand(school)} instead, then have the person run the sign-in command it prints.`);
+        process.exitCode = 2;
+        return;
+    }
+    await interactive(args);
+}
 // 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.
+// setup`, which imports this module — start setup 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));