brightspace-mcp-server 2.0.0 → 3.0.1

package/build/utils/file-validator.js

@@ -6,6 +6,30 @@
 import path from "node:path";
 import { fileTypeFromBuffer } from "file-type";
 import sanitizeFilename from "sanitize-filename";
+import { DownloadError } from "./download-errors.js";
+/**
+ * file-type reports every OLE2 Compound File Binary container as
+ * application/x-cfb. It does not read the CFB directory, so it cannot tell a
+ * .doc from a .xls from an .msi. The three legacy Office entries in
+ * ALLOWED_MIME_TYPES were therefore unreachable and every legacy Office
+ * download failed with a generic error.
+ *
+ * Allowing application/x-cfb outright is not the fix: .msi installers are the
+ * same container, and letting one through under a .doc name is exactly what a
+ * magic-byte allowlist exists to prevent. Reconcile against the declared
+ * extension instead, which admits the formats the allowlist already intended
+ * and still refuses everything else.
+ */
+const CFB_MIME = "application/x-cfb";
+const CFB_EXTENSION_MIMES = {
+    ".doc": "application/msword",
+    ".dot": "application/msword",
+    ".xls": "application/vnd.ms-excel",
+    ".xlt": "application/vnd.ms-excel",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pot": "application/vnd.ms-powerpoint",
+    ".pps": "application/vnd.ms-powerpoint",
+};
 /**
  * Maximum file size for downloads (50 MB).
  * Prevents memory exhaustion from malicious large file requests.
@@ -53,12 +77,20 @@ export const ALLOWED_MIME_TYPES = [
  * @throws Error if path traversal detected
  */
 export function validateDownloadPath(baseDir, filename) {
-    // Decode URL-encoded characters
-    const decoded = decodeURIComponent(filename);
+    // A filename carrying a bare '%' (say "100% Final.doc") makes
+    // decodeURIComponent throw URIError. Brightspace supplies these names, so
+    // that is remote input, and the raw name is the right fallback.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(filename);
+    }
+    catch {
+        decoded = filename;
+    }
     // Sanitize filename (removes path separators, null bytes, etc.)
     const sanitized = sanitizeFilename(decoded);
     if (!sanitized || sanitized.length === 0) {
-        throw new Error("Invalid filename after sanitization");
+        throw new DownloadError("badFilename", "Invalid filename after sanitization");
     }
     // Resolve full path
     const fullPath = path.resolve(baseDir, sanitized);
@@ -66,7 +98,7 @@ export function validateDownloadPath(baseDir, filename) {
     // Verify resolved path is within base directory
     if (!fullPath.startsWith(resolvedBase + path.sep) &&
         fullPath !== resolvedBase) {
-        throw new Error("Path traversal detected");
+        throw new DownloadError("pathTraversal", "Path traversal detected");
     }
     return fullPath;
 }
@@ -79,12 +111,20 @@ export function validateDownloadPath(baseDir, filename) {
  * @returns Detected MIME type and extension
  * @throws Error if file type not allowed
  */
-export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES) {
+export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES, filename) {
     // Try magic byte detection first
     const detected = await fileTypeFromBuffer(buffer);
     if (detected) {
+        if (detected.mime === CFB_MIME) {
+            const ext = filename ? path.extname(filename).toLowerCase() : "";
+            const resolved = CFB_EXTENSION_MIMES[ext];
+            if (resolved && allowedTypes.includes(resolved)) {
+                return { mime: resolved, ext: ext.slice(1) };
+            }
+            throw new DownloadError("unsupportedType", `Compound File Binary with extension '${ext || "none"}' is not an allowed Office format`, CFB_MIME);
+        }
         if (!allowedTypes.includes(detected.mime)) {
-            throw new Error(`File type '${detected.mime}' not allowed. Allowed types: ${allowedTypes.join(", ")}`);
+            throw new DownloadError("unsupportedType", `File type '${detected.mime}' not allowed`, detected.mime);
         }
         return { mime: detected.mime, ext: detected.ext };
     }
@@ -109,7 +149,7 @@ export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES
             }
         }
     }
-    throw new Error("Could not determine file type or type not allowed");
+    throw new DownloadError("undetectableType", "Could not determine file type or type not allowed");
 }
 /**
  * Validate content ID is a positive integer.

package/build/utils/file-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-validator.js","sourceRoot":"","sources":["../../src/utils/file-validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-validator.js","sourceRoot":"","sources":["../../src/utils/file-validator.ts"],"names":[],"mappings":"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"}

package/build/utils/install-sites.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * Find every copy of this package on the machine and report disagreement.
+ *
+ * A single machine can easily hold several copies at different versions: one
+ * per Node version under a version manager, one per npx cache entry, plus a
+ * local checkout. They are installed at different times and nothing keeps them
+ * in step. The failure that motivated this had a v2.0.0 MCP server running
+ * happily while the auth command typed in a shell resolved to v1.2.6, whose
+ * sign-in flow no longer worked, with no way to see the mismatch.
+ *
+ * This scan needs no network, so unlike the registry check it still works
+ * offline, and it catches the problem before anything fails rather than after.
+ *
+ * It reads package.json files and resolves symlinks. It never spawns a
+ * process, never runs npm, and never writes anything.
+ */
+export interface InstallSite {
+    kind: "global" | "npx-cache" | "self";
+    /** The package directory, i.e. .../node_modules/brightspace-mcp-server */
+    dir: string;
+    version: string | null;
+    /** The PATH entry that resolves here, when a shell command points at it. */
+    binPath?: string;
+    isSelf: boolean;
+}
+export interface InstallScanDeps {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    home?: string;
+    /** The running package directory, excluded from "other copies". */
+    selfDir?: string;
+    readVersion?: (packageJsonPath: string) => Promise<string | null>;
+    listDir?: (dir: string) => Promise<string[]>;
+    realpath?: (path: string) => Promise<string>;
+}
+/**
+ * Every copy of this package we can find, including the running one.
+ * Never throws; anything unreadable is simply omitted.
+ */
+export declare function scanInstallSites(deps?: InstallScanDeps): Promise<InstallSite[]>;
+/**
+ * Scan and format in one step. Returns null when there is nothing to say, and
+ * never throws, so callers can treat it as advisory.
+ *
+ * Honors D2L_NO_UPDATE_CHECK, which switches off every version-related notice.
+ */
+export declare function detectSkew(runningVersion: string, deps?: InstallScanDeps): Promise<string | null>;
+/**
+ * A warning about copies that disagree with the running version, or null when
+ * there is nothing worth saying.
+ *
+ * Deliberately quiet: it only speaks when another copy exists at a *different*
+ * version, since a machine with several copies all in step is fine. Copies a
+ * shell command actually resolves to are reported first, because those are the
+ * ones a user can trip over.
+ */
+export declare function formatSkewNotice(sites: InstallSite[], runningVersion: string, home?: string): string | null;
+//# sourceMappingURL=install-sites.d.ts.map

package/build/utils/install-sites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-sites.d.ts","sourceRoot":"","sources":["../../src/utils/install-sites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAaH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;IACtC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9C;AAgFD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAsEzF;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,cAAc,EAAE,MAAM,EACtB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAAE,EACpB,cAAc,EAAE,MAAM,EACtB,IAAI,GAAE,MAAkB,GACvB,MAAM,GAAG,IAAI,CA4Bf"}

package/build/utils/install-sites.js

@@ -0,0 +1,207 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * Find every copy of this package on the machine and report disagreement.
+ *
+ * A single machine can easily hold several copies at different versions: one
+ * per Node version under a version manager, one per npx cache entry, plus a
+ * local checkout. They are installed at different times and nothing keeps them
+ * in step. The failure that motivated this had a v2.0.0 MCP server running
+ * happily while the auth command typed in a shell resolved to v1.2.6, whose
+ * sign-in flow no longer worked, with no way to see the mismatch.
+ *
+ * This scan needs no network, so unlike the registry check it still works
+ * offline, and it catches the problem before anything fails rather than after.
+ *
+ * It reads package.json files and resolves symlinks. It never spawns a
+ * process, never runs npm, and never writes anything.
+ */
+import { readFile, readdir, realpath as fsRealpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { PACKAGE_NAME, GLOBAL_INSTALL_COMMAND, AUTH_COMMAND } from "./commands.js";
+/** Whole-scan budget. A stalled network mount on PATH must not hang startup. */
+const SCAN_BUDGET_MS = 2000;
+/** Most sites named in one notice before it turns into noise. */
+const MAX_REPORTED = 3;
+async function defaultReadVersion(packageJsonPath) {
+    try {
+        const raw = await readFile(packageJsonPath, "utf-8");
+        const version = JSON.parse(raw).version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultListDir(dir) {
+    try {
+        return await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Global `node_modules` roots to probe.
+ *
+ * A plain PATH scan is not enough. A GUI-launched MCP client inherits a
+ * minimal launchd PATH with no version-manager directory in it, so the stale
+ * copy would be invisible. Version-manager roots are therefore enumerated
+ * directly, which is what surfaces a copy sitting under a different Node
+ * version than the one currently running.
+ */
+async function candidateGlobalRoots(env, platform, execPath, home, listDir) {
+    const roots = new Set();
+    const isWin = platform === "win32";
+    // npm's own global-prefix rule, relative to the running node binary.
+    roots.add(isWin
+        ? join(dirname(execPath), "node_modules")
+        : join(dirname(dirname(execPath)), "lib", "node_modules"));
+    // Anything on PATH that looks like a bin directory.
+    for (const entry of (env.PATH ?? "").split(isWin ? ";" : ":")) {
+        if (!entry)
+            continue;
+        if (isWin)
+            roots.add(join(entry, "node_modules"));
+        else if (entry.endsWith(`${sep}bin`))
+            roots.add(join(dirname(entry), "lib", "node_modules"));
+    }
+    if (env.npm_config_prefix) {
+        roots.add(isWin
+            ? join(env.npm_config_prefix, "node_modules")
+            : join(env.npm_config_prefix, "lib", "node_modules"));
+    }
+    if (isWin) {
+        if (env.APPDATA)
+            roots.add(join(env.APPDATA, "npm", "node_modules"));
+    }
+    else {
+        roots.add("/usr/local/lib/node_modules");
+        roots.add("/opt/homebrew/lib/node_modules");
+    }
+    // Version managers, one listing each.
+    const managers = [
+        [join(home, ".nvm", "versions", "node"), ["lib", "node_modules"]],
+        [join(home, ".volta", "tools", "image", "node"), ["lib", "node_modules"]],
+        [join(home, ".local", "share", "fnm", "node-versions"), ["installation", "lib", "node_modules"]],
+        [join(home, ".asdf", "installs", "nodejs"), ["lib", "node_modules"]],
+    ];
+    for (const [base, tail] of managers) {
+        for (const version of await listDir(base)) {
+            roots.add(join(base, version, ...tail));
+        }
+    }
+    return [...roots];
+}
+/**
+ * Every copy of this package we can find, including the running one.
+ * Never throws; anything unreadable is simply omitted.
+ */
+export async function scanInstallSites(deps = {}) {
+    const { env = process.env, platform = process.platform, execPath = process.execPath, home = homedir(), selfDir, readVersion = defaultReadVersion, listDir = defaultListDir, realpath = fsRealpath, } = deps;
+    const found = new Map();
+    const record = async (dir, kind, binPath) => {
+        const key = resolve(dir);
+        const version = await readVersion(join(key, "package.json"));
+        if (version === null && !found.has(key))
+            return; // nothing actually installed here
+        const isSelf = selfDir !== undefined && resolve(selfDir) === key;
+        const existing = found.get(key);
+        found.set(key, {
+            kind: isSelf ? "self" : kind,
+            dir: key,
+            version: version ?? existing?.version ?? null,
+            binPath: binPath ?? existing?.binPath,
+            isSelf,
+        });
+    };
+    const work = (async () => {
+        const roots = await candidateGlobalRoots(env, platform, execPath, home, listDir);
+        await Promise.allSettled(roots.map((root) => record(join(root, PACKAGE_NAME), "global")));
+        // Which copy does the command a user actually types resolve to?
+        const isWin = platform === "win32";
+        if (!isWin) {
+            const shims = ["brightspace-auth", PACKAGE_NAME];
+            await Promise.allSettled((env.PATH ?? "").split(":").filter(Boolean).flatMap((entry) => shims.map(async (shim) => {
+                const binPath = join(entry, shim);
+                try {
+                    const target = await realpath(binPath);
+                    const marker = `${sep}node_modules${sep}${PACKAGE_NAME}${sep}`;
+                    const idx = target.indexOf(marker);
+                    if (idx === -1)
+                        return;
+                    await record(target.slice(0, idx + marker.length - 1), "global", binPath);
+                }
+                catch {
+                    // No such shim here.
+                }
+            })));
+        }
+        // npx cache entries.
+        const npxRoot = join(home, ".npm", "_npx");
+        await Promise.allSettled((await listDir(npxRoot)).map((entry) => record(join(npxRoot, entry, "node_modules", PACKAGE_NAME), "npx-cache")));
+    })();
+    await Promise.race([
+        work,
+        new Promise((r) => setTimeout(r, SCAN_BUDGET_MS).unref?.()),
+    ]);
+    return [...found.values()];
+}
+/**
+ * Scan and format in one step. Returns null when there is nothing to say, and
+ * never throws, so callers can treat it as advisory.
+ *
+ * Honors D2L_NO_UPDATE_CHECK, which switches off every version-related notice.
+ */
+export async function detectSkew(runningVersion, deps = {}) {
+    const env = deps.env ?? process.env;
+    if (env.D2L_NO_UPDATE_CHECK)
+        return null;
+    try {
+        const sites = await scanInstallSites(deps);
+        return formatSkewNotice(sites, runningVersion, deps.home ?? homedir());
+    }
+    catch {
+        return null;
+    }
+}
+function shorten(path, home) {
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+/**
+ * A warning about copies that disagree with the running version, or null when
+ * there is nothing worth saying.
+ *
+ * Deliberately quiet: it only speaks when another copy exists at a *different*
+ * version, since a machine with several copies all in step is fine. Copies a
+ * shell command actually resolves to are reported first, because those are the
+ * ones a user can trip over.
+ */
+export function formatSkewNotice(sites, runningVersion, home = homedir()) {
+    const mismatched = sites
+        .filter((s) => !s.isSelf && s.version !== null && s.version !== runningVersion)
+        .sort((a, b) => Number(Boolean(b.binPath)) - Number(Boolean(a.binPath)));
+    if (mismatched.length === 0)
+        return null;
+    const shown = mismatched.slice(0, MAX_REPORTED);
+    const lines = shown.map((s) => {
+        const where = s.binPath
+            ? `\`${shorten(s.binPath, home)}\` resolves to v${s.version}`
+            : `v${s.version} at ${shorten(s.dir, home)}`;
+        return `  - ${where}`;
+    });
+    const extra = mismatched.length - shown.length;
+    if (extra > 0)
+        lines.push(`  - and ${extra} more`);
+    const resolvable = shown.some((s) => s.binPath);
+    const advice = resolvable
+        ? `An out-of-date auth CLI fails during sign-in. Run \`${GLOBAL_INSTALL_COMMAND}\`, or use \`${AUTH_COMMAND}\`.`
+        : `Run \`${GLOBAL_INSTALL_COMMAND}\` to bring them in line.`;
+    return [
+        `Version mismatch. This process is v${runningVersion}, but other copies of ${PACKAGE_NAME} are installed:`,
+        ...lines,
+        advice,
+    ].join("\n");
+}
+//# sourceMappingURL=install-sites.js.map

package/build/utils/install-sites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-sites.js","sourceRoot":"","sources":["../../src/utils/install-sites.ts"],"names":[],"mappings":"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"}

package/build/utils/self-update.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * Self-healing for the auth CLI.
+ *
+ * The MCP server is launched as `npx -y brightspace-mcp-server@latest`, so it
+ * refetches on every client restart and is effectively always current. The
+ * auth CLI has no such guarantee: a copy installed once with `npm install -g`
+ * stays at that version forever. That is how a machine ended up running a
+ * v2.0.0 server alongside a v1.2.6 auth CLI whose sign-in flow no longer
+ * worked, with nothing to say so.
+ *
+ * When a stale CLI notices it is behind, it re-runs itself through
+ * `npx -y brightspace-mcp-server@latest auth` and hands back that process's
+ * exit code. The user types nothing and is not asked anything; the newest code
+ * simply runs. Note this does not rewrite the old copy on disk -- it is
+ * bypassed, not upgraded. Overwriting it would mean running `npm install -g`
+ * from inside a live process, which is the thing this package deliberately
+ * does not do.
+ *
+ * Opt out with D2L_NO_UPDATE_CHECK.
+ */
+import { type SpawnOptions, type ChildProcess } from "node:child_process";
+/** Set in the child's environment so a re-exec can never recurse. */
+export declare const REEXEC_SENTINEL = "D2L_REEXECED";
+export interface ReexecDeps {
+    env?: NodeJS.ProcessEnv;
+    argv?: string[];
+    installedVersion?: string;
+    fetchImpl?: typeof fetch;
+    /** npx already resolved @latest, so a re-exec would be pointless. */
+    runningFromNpxCache?: boolean;
+    platform?: NodeJS.Platform;
+    spawnImpl?: (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+}
+/**
+ * Flags worth carrying into the re-executed process. Only pass through
+ * option flags: the subcommand is supplied explicitly, and forwarding stray
+ * positional arguments risks changing what the child actually does.
+ */
+export declare function passthroughFlags(argv: string[]): string[];
+/**
+ * Decide, without doing anything, whether a re-exec is warranted.
+ * Split out from the spawn so the policy is testable on its own.
+ */
+export declare function shouldReexec(opts: {
+    env: NodeJS.ProcessEnv;
+    latest: string | null;
+    installedVersion: string;
+    runningFromNpxCache: boolean;
+}): boolean;
+/**
+ * Re-run this command through the latest published release when the running
+ * copy is stale.
+ *
+ * Resolves to the child's exit code when a re-exec happened (the caller should
+ * exit with it and do no further work), or null when the current process
+ * should simply continue.
+ */
+export declare function reexecLatestIfStale(deps?: ReexecDeps): Promise<number | null>;
+//# sourceMappingURL=self-update.d.ts.map

package/build/utils/self-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-update.d.ts","sourceRoot":"","sources":["../../src/utils/self-update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIjF,qEAAqE;AACrE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,SAAS,CAAC,EAAE,CACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,YAAY,KAClB,YAAY,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEzD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAOV;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4CvF"}

package/build/utils/self-update.js

@@ -0,0 +1,92 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * Self-healing for the auth CLI.
+ *
+ * The MCP server is launched as `npx -y brightspace-mcp-server@latest`, so it
+ * refetches on every client restart and is effectively always current. The
+ * auth CLI has no such guarantee: a copy installed once with `npm install -g`
+ * stays at that version forever. That is how a machine ended up running a
+ * v2.0.0 server alongside a v1.2.6 auth CLI whose sign-in flow no longer
+ * worked, with nothing to say so.
+ *
+ * When a stale CLI notices it is behind, it re-runs itself through
+ * `npx -y brightspace-mcp-server@latest auth` and hands back that process's
+ * exit code. The user types nothing and is not asked anything; the newest code
+ * simply runs. Note this does not rewrite the old copy on disk -- it is
+ * bypassed, not upgraded. Overwriting it would mean running `npm install -g`
+ * from inside a live process, which is the thing this package deliberately
+ * does not do.
+ *
+ * Opt out with D2L_NO_UPDATE_CHECK.
+ */
+import { spawn } from "node:child_process";
+import { PACKAGE_NAME } from "./commands.js";
+import { fetchLatestVersion, isNewerVersion, ownNpxCacheDir } from "./update-checker.js";
+/** Set in the child's environment so a re-exec can never recurse. */
+export const REEXEC_SENTINEL = "D2L_REEXECED";
+/**
+ * Flags worth carrying into the re-executed process. Only pass through
+ * option flags: the subcommand is supplied explicitly, and forwarding stray
+ * positional arguments risks changing what the child actually does.
+ */
+export function passthroughFlags(argv) {
+    return argv.slice(2).filter((arg) => arg.startsWith("-"));
+}
+/**
+ * Decide, without doing anything, whether a re-exec is warranted.
+ * Split out from the spawn so the policy is testable on its own.
+ */
+export function shouldReexec(opts) {
+    const { env, latest, installedVersion, runningFromNpxCache } = opts;
+    if (env[REEXEC_SENTINEL])
+        return false; // we are already the child
+    if (env.D2L_NO_UPDATE_CHECK)
+        return false;
+    if (runningFromNpxCache)
+        return false; // npx just fetched this
+    if (latest === null)
+        return false; // registry unreachable, carry on offline
+    return isNewerVersion(latest, installedVersion);
+}
+/**
+ * Re-run this command through the latest published release when the running
+ * copy is stale.
+ *
+ * Resolves to the child's exit code when a re-exec happened (the caller should
+ * exit with it and do no further work), or null when the current process
+ * should simply continue.
+ */
+export async function reexecLatestIfStale(deps = {}) {
+    const { env = process.env, argv = process.argv, installedVersion, fetchImpl = fetch, runningFromNpxCache = ownNpxCacheDir() !== null, platform = process.platform, spawnImpl = spawn, } = deps;
+    if (installedVersion === undefined)
+        return null;
+    // Cheap local checks first, so an opted-out or npx-launched run never even
+    // touches the network.
+    if (env[REEXEC_SENTINEL] || env.D2L_NO_UPDATE_CHECK || runningFromNpxCache)
+        return null;
+    const latest = await fetchLatestVersion(fetchImpl);
+    if (!shouldReexec({ env, latest, installedVersion, runningFromNpxCache }))
+        return null;
+    const args = ["-y", `${PACKAGE_NAME}@latest`, "auth", ...passthroughFlags(argv)];
+    console.error(`\nThis copy is v${installedVersion}; v${latest} is available. ` +
+        `Running the newer version instead.\n`);
+    return await new Promise((resolve) => {
+        let child;
+        try {
+            child = spawnImpl(platform === "win32" ? "npx.cmd" : "npx", args, {
+                stdio: "inherit",
+                env: { ...env, [REEXEC_SENTINEL]: "1" },
+                shell: platform === "win32",
+            });
+        }
+        catch {
+            resolve(null); // could not launch npx, fall back to running ourselves
+            return;
+        }
+        // If npx itself cannot start, run the stale copy rather than failing.
+        child.on("error", () => resolve(null));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+//# sourceMappingURL=self-update.js.map

package/build/utils/self-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-update.js","sourceRoot":"","sources":["../../src/utils/self-update.ts"],"names":[],"mappings":"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"}