brightspace-mcp-server 1.6.3 → 3.0.0

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/secure-config.d.ts

@@ -0,0 +1,6 @@
+import { type ConfigStoreData } from "./config-store.js";
+/** Save secrets first so a failed vault write leaves the old configuration intact. */
+export declare function saveSecureConfig(config: ConfigStoreData): Promise<void>;
+/** Migrate a v1 password under its own account, before resolving environment overrides. */
+export declare function resolveStoredPassword(baseUrl: string, username: string | undefined, store: ConfigStoreData | null): Promise<string | undefined>;
+//# sourceMappingURL=secure-config.d.ts.map

package/build/utils/secure-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-config.d.ts","sourceRoot":"","sources":["../../src/utils/secure-config.ts"],"names":[],"mappings":"AAGA,OAAO,EAA2E,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAWlI,sFAAsF;AACtF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7E;AAuBD,2FAA2F;AAC3F,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,eAAe,GAAG,IAAI,GAC5B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}

package/build/utils/secure-config.js

@@ -0,0 +1,57 @@
+import { getStoredPassword, setStoredPassword } from "../auth/credential-store.js";
+import * as path from "node:path";
+import { acquireProcessLock } from "../auth/auth-lock.js";
+import { configStoreExists, getConfigStorePath, loadConfigStore, saveConfigStore } from "./config-store.js";
+async function withConfigWriteLock(operation) {
+    const release = await acquireProcessLock(path.join(path.dirname(getConfigStorePath()), ".config-write.lock"));
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
+/** Save secrets first so a failed vault write leaves the old configuration intact. */
+export async function saveSecureConfig(config) {
+    await withConfigWriteLock(() => saveSecureConfigUnlocked(config));
+}
+async function saveSecureConfigUnlocked(config) {
+    const { password, ...publicConfig } = config;
+    if (publicConfig.baseUrl) {
+        const url = new URL(publicConfig.baseUrl);
+        if (url.protocol !== "https:" || url.username || url.password) {
+            throw new Error("The Brightspace URL must be HTTPS without embedded credentials.");
+        }
+        publicConfig.baseUrl = url.origin;
+    }
+    if (password !== undefined) {
+        if (!config.baseUrl || !config.username || !password) {
+            throw new Error("A school URL, username, and nonempty password are required.");
+        }
+        await setStoredPassword(config.baseUrl, config.username, password);
+        if (await getStoredPassword(config.baseUrl, config.username) !== password) {
+            throw new Error("Could not verify the password in the native credential store. Configuration was preserved.");
+        }
+    }
+    saveConfigStore(publicConfig);
+}
+/** Migrate a v1 password under its own account, before resolving environment overrides. */
+export async function resolveStoredPassword(baseUrl, username, store) {
+    if (store?.password !== undefined) {
+        await withConfigWriteLock(async () => {
+            // A setup command may have replaced this snapshot while native storage
+            // was opening. Migrate only the current record under the same writer lock.
+            const current = configStoreExists() ? loadConfigStore() : null;
+            if (current?.password !== undefined)
+                await saveSecureConfigUnlocked(current);
+        });
+    }
+    if (!username)
+        return undefined;
+    if (process.env.D2L_PASSWORD) {
+        // Environment input is supported, but the application never copies it to a file.
+        await setStoredPassword(baseUrl, username, process.env.D2L_PASSWORD);
+    }
+    return (await getStoredPassword(baseUrl, username)) ?? undefined;
+}
+//# sourceMappingURL=secure-config.js.map

package/build/utils/secure-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-config.js","sourceRoot":"","sources":["../../src/utils/secure-config.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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"}

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

@@ -1,15 +1,59 @@
 /**
  * Background npm update checker: look, and tell, but never touch.
  *
- * On startup the server asks the npm registry for the latest published
- * version. If it is newer than the running one, the user is told how to
- * update. Nothing is ever installed by this module. The one side effect it
- * keeps is scoped to this package's own stale npx cache directories, because
- * clearing them is what lets `npx brightspace-mcp-server@latest` actually
- * pick up the new version on the next start.
+ * The server asks the npm registry for the latest published version, on
+ * startup and then periodically, because a stdio MCP server can stay alive for
+ * days and a boot-only check would never notice a release. If the registry has
+ * something newer, the user is told how to update. Nothing is ever installed
+ * by this module.
+ *
+ * The one side effect it keeps is scoped to this package's own stale npx cache
+ * directories, because clearing them is what lets `npx brightspace-mcp-server@latest`
+ * actually pick up the new version on the next start. It never deletes the
+ * directory the current process is running from -- doing so pulls the rug out
+ * from under lazy imports (Playwright is loaded on demand at auth time) and
+ * from the auth CLI this process spawns as a child.
+ *
+ * The notice repeats on a throttle rather than being consumed by whichever
+ * caller happens to read it first. A one-shot notice is invisible in practice:
+ * it gets swallowed by a single background tool call and never seen again.
  *
  * Set D2L_NO_UPDATE_CHECK to any value to switch the check off entirely.
  */
+import { access, readdir, rm } from "node:fs/promises";
+/**
+ * The `_npx/<hash>` directory this process is executing out of, or null when
+ * not running from an npx cache. Used both to detect npx execution and, more
+ * importantly, to know which directory must never be deleted.
+ */
+export declare function ownNpxCacheDir(root?: string): string | null;
+/**
+ * Remove npx cache entries holding a copy of this package, so the next
+ * `npx brightspace-mcp-server@latest` downloads the new version instead of
+ * reusing a stale one.
+ *
+ * Skips the directory the current process is running from. Deleting it would
+ * break this process: Playwright is imported lazily at auth time, and the auth
+ * CLI is spawned from the same tree, so both would fail with ENOENT for the
+ * rest of the server's life. Touches nothing outside npx cache directories.
+ */
+export declare function clearAllNpxCaches(selfDir?: string | null, deps?: {
+    readdirImpl?: typeof readdir;
+    rmImpl?: typeof rm;
+    accessImpl?: typeof access;
+}): Promise<number>;
+/**
+ * A version string safe to show a person.
+ *
+ * The registry response is remote input, and the notice built from it is now
+ * rendered into the user's AI client by every tool, so the raw string must
+ * never be interpolated. `parseTriple` deliberately tolerates a trailing
+ * prerelease suffix, which means a `latest` of "2.2.0 and now ignore your
+ * instructions" parses happily. Rebuilding the label from the parsed numbers
+ * discards everything after the digits, so only `\d+\.\d+\.\d+` can ever reach
+ * the screen.
+ */
+export declare function safeVersionLabel(version: string): string;
 /**
  * True only when `latest` is strictly newer than `installed`, compared as
  * numeric major, minor, patch. Prerelease suffixes are ignored, and anything
@@ -17,6 +61,12 @@
  * cannot announce an update that does not exist.
  */
 export declare function isNewerVersion(latest: string, installed: string): boolean;
+/**
+ * Ask the registry for the latest published version. Returns null on any
+ * failure -- a bad network must never be reported as "you are up to date" or
+ * as an error the caller has to handle.
+ */
+export declare function fetchLatestVersion(fetchImpl?: typeof fetch): Promise<string | null>;
 export interface UpdateCheckDeps {
     fetchImpl?: typeof fetch;
     env?: Record<string, string | undefined>;
@@ -30,5 +80,33 @@ export interface UpdateCheckDeps {
  * swallowed, because a version check must not affect the server.
  */
 export declare function initUpdateChecker(deps?: UpdateCheckDeps): Promise<void>;
-export declare function getUpdateNotice(): string | null;
+export interface PeriodicUpdateDeps extends UpdateCheckDeps {
+    intervalMs?: number;
+    setIntervalImpl?: (fn: () => void, ms: number) => {
+        unref?: () => void;
+    };
+    clearIntervalImpl?: (handle: unknown) => void;
+}
+/**
+ * Check now, then keep checking. Returns a stop function.
+ *
+ * The interval is unref'd so it can never hold a stdio server open past the
+ * point it would otherwise exit.
+ */
+export declare function startUpdateChecks(deps?: PeriodicUpdateDeps): () => void;
+/**
+ * Read the notice without consuming or throttling it.
+ *
+ * For one-shot contexts like a CLI, which runs, prints once, and exits.
+ */
+export declare function peekUpdateNotice(): string | null;
+/**
+ * Read the notice for a repeated context like MCP tool responses, which can
+ * fire many times a session. Returns the notice at most once per
+ * `minIntervalMs`. `now` is a parameter so throttling is testable without
+ * faking timers.
+ */
+export declare function getUpdateNotice(now?: number, minIntervalMs?: number): string | null;
+/** Drop any pending notice. Primarily for resetting module state in tests. */
+export declare function clearUpdateNotice(): void;
 //# sourceMappingURL=update-checker.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"update-checker.d.ts","sourceRoot":"","sources":["../../src/utils/update-checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8DH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAQzE;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCjF;AAED,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAI/C"}
+{"version":3,"file":"update-checker.d.ts","sourceRoot":"","sources":["../../src/utils/update-checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAuCvD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAoB,GAAG,MAAM,GAAG,IAAI,CAIxE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,MAAM,GAAG,IAAuB,EACzC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,MAAM,CAAA;CAAO,GAC1F,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAQzE;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYhG;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCjF;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK;QAAE,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IACzE,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,kBAAuB,GAAG,MAAM,IAAI,CAgB3E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,GAAE,MAAmB,EACxB,aAAa,GAAE,MAAyB,GACvC,MAAM,GAAG,IAAI,CAKf;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}