@jamestesting888/tum-mcp 0.5.0 → 0.6.1

package/npm/npm-command.mjs

@@ -0,0 +1,96 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join, basename, resolve, relative, isAbsolute, sep } from 'node:path';
+
+export const packageName = '@jamestesting888/tum-mcp';
+
+function canonical(value) {
+  let path = resolve(value.replace(/^~(?=$|[/\\])/, homedir()));
+  const tail = [];
+  while (!existsSync(path)) { tail.unshift(basename(path)); path = dirname(path); }
+  return join(realpathSync(path), ...tail);
+}
+
+export function packageStorage(root, dataDirectory) {
+  const home = homedir();
+  const base = process.platform === 'darwin' ? join(home, 'Library/Application Support')
+    : process.platform === 'win32' ? process.env.LOCALAPPDATA || join(home, 'AppData/Local')
+    : process.env.XDG_DATA_HOME || join(home, '.local/share');
+  const storage = {
+    TUM_MCP_DATA_DIR: canonical(dataDirectory),
+    TUM_MCP_CONFIG_DIR: canonical(process.env.TUM_MCP_CONFIG_DIR || join(dataDirectory, 'config')),
+    TUM_MOODLE_DATA_DIR: canonical(process.env.TUM_MOODLE_DATA_DIR || join(base, 'TUMMoodle')),
+    TUM_MOODLE_DOWNLOAD_DIR: canonical(process.env.TUM_MOODLE_DOWNLOAD_DIR || join(home, 'Downloads/TUM Moodle')),
+  };
+  const config = storage.TUM_MCP_CONFIG_DIR;
+  const settings = join(config, 'preferences.json');
+  let workspace = join(home, 'University');
+  if (existsSync(settings)) {
+    try {
+      const prefs = JSON.parse(readFileSync(settings, 'utf8'));
+      if (prefs.workspace_root !== undefined) {
+        if (typeof prefs.workspace_root !== 'string') throw new Error('Invalid storage path');
+        workspace = prefs.workspace_root;
+      }
+    } catch { throw new Error('Storage settings could not be verified; package files and saved data were preserved.'); }
+  }
+  for (const path of [...Object.values(storage), workspace]) {
+    const inside = relative(root, canonical(path));
+    if (inside === '' || (inside.split(sep)[0] !== '..' && !isAbsolute(inside))) {
+      throw new Error('Package installation overlaps saved data or course work. Move that data outside the package before update/removal.');
+    }
+  }
+  return storage;
+}
+
+export function npmCli() {
+  const paths = (process.env.PATH || '').split(delimiter);
+  const candidates = [process.env.npm_execpath,
+    join(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js'),
+    join(dirname(dirname(process.execPath)), 'lib/node_modules/npm/bin/npm-cli.js'),
+    ...paths.flatMap(path => [join(path, 'npm'), join(path, 'node_modules/npm/bin/npm-cli.js')])];
+  for (const path of candidates) {
+    if (!path || !existsSync(path)) continue;
+    const resolved = realpathSync(path);
+    if (basename(resolved) !== 'npm-cli.js') continue;
+    const manifest = join(dirname(dirname(resolved)), 'package.json');
+    if (existsSync(manifest) && JSON.parse(readFileSync(manifest, 'utf8')).name === 'npm') return resolved;
+  }
+  throw new Error('npm could not be located beside Node or on PATH. Install Node.js with npm, then retry.');
+}
+
+export function runNpm(cli, args, capture = false) {
+  const result = spawnSync(process.execPath, [cli, ...args, '--ignore-scripts', '--no-audit', '--no-fund', '--no-update-notifier'], {
+    shell: false, stdio: capture ? ['ignore', 'pipe', 'inherit'] : 'inherit', encoding: 'utf8', timeout: 600000,
+  });
+  if (result.error || result.status !== 0) throw new Error('npm operation failed. Saved data and retained client runtimes were preserved; resolve the npm error and retry.');
+  return capture ? result.stdout.trim() : '';
+}
+
+export function installationTarget(root) {
+  const modules = dirname(dirname(root));
+  if (basename(modules) !== 'node_modules' || modules.split(/[\\/]/).some(part => ['.pnpm', '_npx'].includes(part))) {
+    throw new Error('Package management requires an npm installation. Use update --local for a source/pinned build.');
+  }
+  if (`${basename(dirname(root))}/${basename(root)}` !== packageName) {
+    throw new Error('Automatic package management requires the original package name; aliases were preserved.');
+  }
+  const parent = dirname(modules);
+  const prefix = process.platform === 'win32' ? parent : dirname(parent);
+  const shim = process.platform === 'win32' ? join(prefix, 'tum-mcp.cmd') : join(prefix, 'bin/tum-mcp');
+  if (existsSync(shim)) {
+    const owned = process.platform === 'win32'
+      ? readFileSync(shim, 'utf8').replaceAll('\\', '/').includes('node_modules/@jamestesting888/tum-mcp/npm/tum-mcp.mjs')
+      : realpathSync(shim) === join(root, 'npm/tum-mcp.mjs');
+    if (owned && (process.platform === 'win32' || basename(parent) === 'lib')) return { prefix, global: true };
+  }
+  const manifest = join(parent, 'package.json');
+  if (existsSync(manifest)) {
+    const project = JSON.parse(readFileSync(manifest, 'utf8'));
+    if (['dependencies', 'devDependencies', 'optionalDependencies'].some(key => project[key]?.[packageName])) {
+      return { prefix: parent, global: false };
+    }
+  }
+  throw new Error('The npm installation prefix could not be verified; package files were preserved.');
+}

package/npm/package-manager.mjs

@@ -0,0 +1,109 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { copyFile, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { acquireLock } from './lock.mjs';
+import { installationTarget, npmCli, packageName, packageStorage, runNpm } from './npm-command.mjs';
+
+function runLauncher(root, args, quiet = false) {
+  const result = spawnSync(process.execPath, [join(root, 'npm/tum-mcp.mjs'), ...args], {
+    stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit', encoding: 'utf8', shell: false, timeout: 600000,
+  });
+  if (result.error || result.status !== 0) {
+    if (quiet) process.stderr.write((result.stdout || '') + (result.stderr || ''));
+    throw new Error(`${args[0]} did not complete. Saved data and customized client files were preserved; review the details and retry.`);
+  }
+}
+
+function versionParts(version) {
+  const match = typeof version === 'string' && version.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*))?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/);
+  if (!match) throw new Error('npm returned an invalid package version.');
+  const prerelease = match[4]?.split('.') || [];
+  if (prerelease.some(part => /^0\d+$/.test(part))) throw new Error('npm returned an invalid prerelease version.');
+  return { core: match.slice(1, 4).map(BigInt), prerelease };
+}
+
+export function newerVersion(latest, current) {
+  const left = versionParts(latest), right = versionParts(current);
+  for (let i = 0; i < left.core.length; i++) if (left.core[i] !== right.core[i]) return left.core[i] > right.core[i];
+  const a = left.prerelease, b = right.prerelease;
+  if (!a.length || !b.length) return !a.length && Boolean(b.length);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] === undefined) return false;
+    if (b[i] === undefined) return true;
+    if (a[i] === b[i]) continue;
+    const numericA = /^\d+$/.test(a[i]), numericB = /^\d+$/.test(b[i]);
+    if (numericA && numericB) return BigInt(a[i]) > BigInt(b[i]);
+    if (numericA !== numericB) return numericB;
+    return a[i] > b[i];
+  }
+  return false;
+}
+
+async function operate(job) {
+  const release = await acquireLock(job.target.prefix, 'tum-mcp-package');
+  try {
+    const scope = ['--prefix', job.target.prefix, `--global=${job.target.global}`];
+    if (job.action === 'uninstall') {
+      const configured = existsSync(join(job.dataDirectory, 'runtime.json')) ||
+        existsSync(join(job.configDirectory, 'clients'));
+      if (configured || job.args.some(arg => ['--purge-runtime', '--forget-credentials'].includes(arg))) {
+        runLauncher(job.root, ['uninstall', '--keep-package', ...job.args]);
+      }
+      runNpm(job.npm, ['uninstall', ...scope, packageName]);
+      console.log('TUM MCP package and managed client setup removed. Saved user data was retained unless explicitly requested.');
+      return;
+    }
+    const current = JSON.parse(readFileSync(join(job.root, 'package.json'), 'utf8')).version;
+    const latest = JSON.parse(runNpm(job.npm, ['view', `${packageName}@latest`, 'version', '--json', ...scope], true));
+    if (!newerVersion(latest, current)) {
+      console.log(`Installed ${current}; no newer npm release. Refreshing configured clients.`);
+      runLauncher(job.root, ['update', '--local']);
+      return;
+    }
+    console.log(`Preparing TUM MCP ${latest}.`);
+    const packed = JSON.parse(runNpm(job.npm, ['pack', `${packageName}@${latest}`, '--pack-destination', job.temporary, '--json', ...scope], true));
+    if (!Array.isArray(packed) || packed.length !== 1 || packed[0].name !== packageName || packed[0].version !== latest || basename(packed[0].filename) !== packed[0].filename) {
+      throw new Error('npm package metadata did not match the selected release.');
+    }
+    const archive = join(job.temporary, packed[0].filename);
+    const staging = join(job.temporary, 'prepared');
+    runNpm(job.npm, ['install', '--prefix', staging, '--global=false', archive], true);
+    const prepared = join(staging, 'node_modules', packageName);
+    runLauncher(prepared, ['setup'], true);
+    // Only a healthy prepared release may replace the user's npm installation.
+    runNpm(job.npm, ['install', ...scope, job.target.global ? archive : `${packageName}@${latest}`]);
+    if (JSON.parse(readFileSync(join(job.root, 'package.json'), 'utf8')).version !== latest) throw new Error('npm did not install the selected version; client activation was stopped.');
+    runLauncher(job.root, ['update', '--local']);
+    console.log(`Updated TUM MCP to ${latest}. Restart clients to load refreshed skills.`);
+  } finally { await release(); }
+}
+
+export async function managePackage(action, args, dataDirectory) {
+  const root = dirname(dirname(fileURLToPath(import.meta.url)));
+  const inside = relative(root, process.cwd());
+  if (inside === '' || (inside.split(sep)[0] !== '..' && !isAbsolute(inside))) throw new Error('Run package update/removal from outside the installed package directory.');
+  const target = installationTarget(root);
+  const storage = packageStorage(root, dataDirectory);
+  const configDirectory = storage.TUM_MCP_CONFIG_DIR;
+  const npm = npmCli();
+  const temporary = await mkdtemp(join(tmpdir(), 'tum-mcp-package-'));
+  try {
+    for (const name of ['package-manager.mjs', 'npm-command.mjs', 'lock.mjs']) await copyFile(join(root, 'npm', name), join(temporary, name));
+    const job = { action, args, root, dataDirectory, configDirectory, target, npm, temporary };
+    const path = join(temporary, 'job.json');
+    await writeFile(path, JSON.stringify(job), { mode: 0o600, flag: 'wx' });
+    // This worker and its cwd survive Windows replacing/removing the package files.
+    const result = spawnSync(process.execPath, [join(temporary, 'package-manager.mjs'), '--job', path], {
+      cwd: temporary, stdio: 'inherit', shell: false, env: { ...process.env, ...storage },
+    });
+    return result.status ?? (result.signal === 'SIGINT' ? 130 : 2);
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+if (process.argv[1] && process.argv[2] === '--job' && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { await operate(JSON.parse(readFileSync(process.argv[3], 'utf8'))); }
+  catch (error) { console.error(error.message); process.exitCode = 2; }
+}

package/npm/runtime.mjs

@@ -1,96 +1,212 @@
 import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { chmod, mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { chmod, mkdir, mkdtemp, rename, rm, rmdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { download } from './download.mjs';
+import { acquireLock } from './lock.mjs';
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const pins = JSON.parse(readFileSync(join(packageRoot, 'npm/uv-artifacts.json'), 'utf8'));
+const packageVersion = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
 
 export function dataRoot() {
-  if (process.env.TUM_MCP_DATA_DIR) return process.env.TUM_MCP_DATA_DIR;
-  if (process.platform === 'darwin') return join(homedir(), 'Library/Application Support/TUMMCP');
-  if (process.platform === 'win32') return join(process.env.LOCALAPPDATA || join(homedir(), 'AppData/Local'), 'TUMMCP');
-  return join(process.env.XDG_DATA_HOME || join(homedir(), '.local/share'), 'TUMMCP');
+  let path = process.env.TUM_MCP_DATA_DIR;
+  if (!path) {
+    if (process.platform === 'darwin') path = join(homedir(), 'Library/Application Support/TUMMCP');
+    else if (process.platform === 'win32') path = join(process.env.LOCALAPPDATA || join(homedir(), 'AppData/Local'), 'TUMMCP');
+    else path = join(process.env.XDG_DATA_HOME || join(homedir(), '.local/share'), 'TUMMCP');
+  }
+  path = resolve(path.replace(/^~(?=$|[/\\])/, homedir()));
+  const tail = [];
+  while (!existsSync(path)) { tail.unshift(basename(path)); path = dirname(path); }
+  return join(realpathSync(path), ...tail);
+}
+
+function manifest() {
+  const value = JSON.parse(readFileSync(join(packageRoot, 'npm/backend/manifest.json'), 'utf8'));
+  if (!/^[a-zA-Z0-9_.-]+\.whl$/.test(value.wheel) ||
+      !/^[a-f0-9]{64}$/.test(value.wheelSha256) || !/^[a-f0-9]{64}$/.test(value.requirementsSha256)) {
+    throw new Error('Invalid backend manifest; reinstall the npm package.');
+  }
+  return value;
 }
 
-function run(executable, args) {
-  const env = { ...process.env };
-  delete env.VIRTUAL_ENV; delete env.PYTHONPATH; delete env.PYTHONHOME;
-  const result = spawnSync(executable, args, { env, stdio: ['ignore', 'inherit', 'inherit'], shell: false, timeout: 600000 });
-  if (result.error) throw new Error(`Managed runtime subprocess could not start (${result.error.code || 'unknown'}); check executable permissions and mount options.`);
-  if (result.status !== 0) throw new Error('Managed runtime setup failed; inspect the diagnostics above.');
+export function runtimeIdentity(value = manifest()) {
+  return createHash('sha256').update(JSON.stringify({ schema: 2, wheel: value.wheelSha256,
+    requirements: value.requirementsSha256, python: pins.python })).digest('hex');
 }
 
+function controlDirectory(identity) { return join(dataRoot(), 'runtimes', identity); }
+function pythonPath(runtime) { return join(runtime, process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python'); }
+
 export function currentPython() {
   try {
-    const current = JSON.parse(readFileSync(join(dataRoot(), 'runtime.json'), 'utf8'));
-    if (!/^[a-f0-9]{64}$/.test(current.identity)) return null;
-    const manifest = JSON.parse(readFileSync(join(packageRoot, 'npm/backend/manifest.json'), 'utf8'));
-    if (current.identity !== manifest.wheelSha256) return null;
-    const runtime = join(dataRoot(), 'runtimes', current.identity);
-    const expected = join(runtime, process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python');
-    if (current.python !== expected || !existsSync(expected)) return null;
-    if (readFileSync(join(runtime, '.tum-mcp-ready'), 'utf8') !== current.identity) return null;
+    const identity = runtimeIdentity();
+    const control = controlDirectory(identity);
+    const selected = JSON.parse(readFileSync(join(control, 'current.json'), 'utf8'));
+    if (selected.schema !== 2 || selected.identity !== identity || !/^env-[a-zA-Z0-9]+$/.test(selected.generation)) return null;
+    const runtime = join(control, selected.generation);
+    const expected = pythonPath(runtime);
+    if (selected.python !== expected || !existsSync(expected)) return null;
+    if ([join(dataRoot(), 'runtimes'), control, runtime, join(runtime, '.tum-mcp-ready')].some(path => lstatSync(path).isSymbolicLink())) return null;
+    if (readFileSync(join(runtime, '.tum-mcp-ready'), 'utf8') !== identity) return null;
     return expected;
   } catch { return null; }
 }
 
+function run(executable, args, { quiet = false, timeout = 600000 } = {}) {
+  const env = { ...process.env }; delete env.VIRTUAL_ENV; delete env.PYTHONPATH; delete env.PYTHONHOME;
+  const result = spawnSync(executable, args, { env, stdio: quiet ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'inherit', 'inherit'], shell: false, timeout });
+  if (result.error) throw new Error(`Managed runtime subprocess could not start (${result.error.code || 'unknown'}); check permissions and retry setup.`);
+  if (result.status !== 0) throw new Error('Managed runtime setup failed; the previous runtime was retained.');
+  return result;
+}
+
+function healthy(python) {
+  try {
+    const result = run(python, ['-I', '-c', 'from tum_mcp.server import server; from tum_mcp import __version__; print(__version__)'], { quiet: true, timeout: 30000 });
+    return result.stdout.toString().trim() === packageVersion;
+  } catch { return false; }
+}
+
+async function atomicWrite(path, data) {
+  const temporary = `${path}.${randomUUID()}.pending`;
+  try {
+    await writeFile(temporary, data, { mode: 0o600, flag: 'wx' });
+    await rename(temporary, path);
+  } finally { await rm(temporary, { force: true }); }
+}
+
 function matchingUv(executable) {
   const found = spawnSync(executable, ['--version'], { encoding: 'utf8', shell: false, timeout: 10000 });
   return found.status === 0 && found.stdout.trim().split(' ')[1] === pins.version;
 }
 
+async function uvExecutable() {
+  const cached = join(dataRoot(), process.platform === 'win32' ? 'uv.exe' : 'uv');
+  if (matchingUv('uv')) return 'uv';
+  if (matchingUv(cached)) {
+    await atomicWrite(join(dataRoot(), 'uv-owner.json'), JSON.stringify({ sha256: createHash('sha256').update(readFileSync(cached)).digest('hex') }));
+    return cached;
+  }
+  const systems = { darwin: 'apple-darwin', linux: 'unknown-linux-gnu', win32: 'pc-windows-msvc' };
+  const arches = { arm64: 'aarch64', x64: 'x86_64' };
+  const target = `${arches[process.arch]}-${systems[process.platform]}`;
+  const artifact = pins.artifacts[target];
+  if (!artifact) throw new Error('Unsupported platform/architecture; use a documented manual installation.');
+  const temporary = await mkdtemp(join(dataRoot(), 'bootstrap-'));
+  try {
+    const archive = join(temporary, process.platform === 'win32' ? 'uv.zip' : 'uv.tar.gz');
+    await download(artifact.url, archive, artifact.sha256);
+    run('tar', ['-xf', archive, '-C', temporary]);
+    const extracted = process.platform === 'win32' ? join(temporary, 'uv.exe') : join(temporary, `uv-${target}`, 'uv');
+    await rename(extracted, cached);
+    if (process.platform !== 'win32') await chmod(cached, 0o700);
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+  await atomicWrite(join(dataRoot(), 'uv-owner.json'), JSON.stringify({ sha256: createHash('sha256').update(readFileSync(cached)).digest('hex') }));
+  return cached;
+}
+
+export function acquireSetupLock() { return acquireLock(dataRoot()); }
+
 export async function ensureRuntime() {
   const backend = join(packageRoot, 'npm/backend');
-  const manifest = JSON.parse(readFileSync(join(backend, 'manifest.json'), 'utf8'));
-  if (!/^[a-zA-Z0-9_.-]+\.whl$/.test(manifest.wheel)) throw new Error('Invalid backend manifest.');
-  for (const [name, expected] of [[manifest.wheel, manifest.wheelSha256], ['requirements.txt', manifest.requirementsSha256]]) {
+  const value = manifest();
+  for (const [name, expected] of [[value.wheel, value.wheelSha256], ['requirements.txt', value.requirementsSha256]]) {
     if (createHash('sha256').update(readFileSync(join(backend, name))).digest('hex') !== expected) throw new Error('Backend integrity check failed.');
   }
-  const identity = manifest.wheelSha256;
-  const runtime = join(dataRoot(), 'runtimes', identity);
-  const python = join(runtime, process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python');
+  const identity = runtimeIdentity(value);
   await mkdir(dataRoot(), { recursive: true, mode: 0o700 });
-  // A per-runtime directory lock prevents concurrent setup from corrupting a venv.
-  const lock = join(dataRoot(), 'setup.lock');
-  try { await mkdir(lock, { mode: 0o700 }); }
-  catch (error) { if (error.code === 'EEXIST') throw new Error('Another setup is running; retry when it finishes.'); throw error; }
+  const release = await acquireSetupLock();
+  let preparing;
   try {
-    const ready = join(runtime, '.tum-mcp-ready');
-    if (!existsSync(python) || !existsSync(ready) || readFileSync(ready, 'utf8') !== identity) {
-      const cachedUv = join(dataRoot(), process.platform === 'win32' ? 'uv.exe' : 'uv');
-      let uv = matchingUv('uv') ? 'uv' : matchingUv(cachedUv) ? cachedUv : null;
-      if (!uv) {
-        const systems = { darwin: 'apple-darwin', linux: 'unknown-linux-gnu', win32: 'pc-windows-msvc' };
-        const arches = { arm64: 'aarch64', x64: 'x86_64' };
-        const target = `${arches[process.arch]}-${systems[process.platform]}`;
-        const artifact = pins.artifacts[target];
-        if (!artifact) throw new Error('Unsupported platform/architecture; use a documented manual installation.');
-        const temporary = await mkdtemp(join(dataRoot(), 'bootstrap-'));
-        try {
-          const archive = join(temporary, process.platform === 'win32' ? 'uv.zip' : 'uv.tar.gz');
-          await download(artifact.url, archive, artifact.sha256);
-          run('tar', ['-xf', archive, '-C', temporary]);
-          const extracted = process.platform === 'win32' ? join(temporary, 'uv.exe') : join(temporary, `uv-${target}`, 'uv');
-          uv = join(dataRoot(), process.platform === 'win32' ? 'uv.exe' : 'uv');
-          await rename(extracted, uv); if (process.platform !== 'win32') await chmod(uv, 0o700);
-        } finally { await rm(temporary, { recursive: true, force: true }); }
+    let python = currentPython();
+    if (!python || !healthy(python)) {
+      const uv = await uvExecutable();
+      const control = controlDirectory(identity);
+      for (const path of [join(dataRoot(), 'runtimes'), control]) {
+        if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error('Symbolic runtime directory preserved; review it locally.');
       }
-      await mkdir(dirname(runtime), { recursive: true, mode: 0o700 });
-      if (existsSync(runtime)) await rm(runtime, { recursive: true, force: true });
-      run(uv, ['venv', '--managed-python', '--python', pins.python, runtime]);
+      await mkdir(control, { recursive: true, mode: 0o700 });
+      await atomicWrite(join(control, 'runtime-owner.json'), JSON.stringify({ kind: 'tum-mcp-runtime', schema: 2, identity }));
+      preparing = await mkdtemp(join(control, 'env-'));
+      python = pythonPath(preparing);
+      run(uv, ['venv', '--managed-python', '--python', pins.python, preparing]);
       run(uv, ['pip', 'sync', '--python', python, '--require-hashes', '--only-binary', ':all:', join(backend, 'requirements.txt')]);
-      run(uv, ['pip', 'install', '--python', python, '--no-deps', '--no-index', join(backend, manifest.wheel)]);
+      run(uv, ['pip', 'install', '--python', python, '--no-deps', '--no-index', join(backend, value.wheel)]);
+      if (!healthy(python)) throw new Error('New runtime validation failed; the previous runtime was retained.');
+      await atomicWrite(join(preparing, '.tum-mcp-ready'), identity);
+      const selected = JSON.stringify({ schema: 2, identity, generation: basename(preparing), python });
+      await atomicWrite(join(control, 'current.json'), selected);
+      // Published generations are never removed: existing clients may still pin one.
+      preparing = undefined;
+      await atomicWrite(join(dataRoot(), 'runtime.json'), selected);
     }
-    try { run(python, ['-I', '-m', 'tum_mcp', 'version']); }
-    catch (error) { await rm(ready, { force: true }); throw error; }
-    await writeFile(ready, identity, { mode: 0o600 });
-    await writeFile(join(dataRoot(), 'runtime.pending.json'), JSON.stringify({ identity, python }), { mode: 0o600 });
-    await rename(join(dataRoot(), 'runtime.pending.json'), join(dataRoot(), 'runtime.json'));
+    const selected = readFileSync(join(controlDirectory(identity), 'current.json'), 'utf8');
+    const global = join(dataRoot(), 'runtime.json');
+    if (!existsSync(global) || readFileSync(global, 'utf8') !== selected) await atomicWrite(global, selected);
+    await rm(join(dataRoot(), 'runtime-removal.pending'), { force: true });
     return python;
-  } finally { await rm(lock, { recursive: true, force: true }); }
+  } finally {
+    try { if (preparing) await rm(preparing, { recursive: true, force: true }); }
+    finally { await release(); }
+  }
+}
+
+
+export async function removeRuntimeFiles() {
+  const root = dataRoot();
+  const directory = join(root, 'runtimes');
+  if (!existsSync(join(root, 'runtime-removal.pending'))) throw new Error('Runtime removal must be requested with uninstall --all --purge-runtime.');
+  const owned = [];
+  if (existsSync(directory)) {
+    if (lstatSync(directory).isSymbolicLink()) throw new Error('Symbolic runtime directory preserved for review.');
+    for (const name of readdirSync(directory)) {
+      const runtime = join(directory, name);
+      if (!/^[a-f0-9]{64}$/.test(name) || lstatSync(runtime).isSymbolicLink()) throw new Error('Unrecognized runtime files were preserved for review.');
+      let verified = false;
+      const owner = join(runtime, 'runtime-owner.json');
+      if (existsSync(owner) && !lstatSync(owner).isSymbolicLink()) {
+        const record = JSON.parse(readFileSync(owner, 'utf8'));
+        verified = record.kind === 'tum-mcp-runtime' && record.schema === 2 && record.identity === name;
+      }
+      const legacy = join(runtime, '.tum-mcp-ready');
+      if (!verified && existsSync(legacy) && !lstatSync(legacy).isSymbolicLink()) verified = readFileSync(legacy, 'utf8') === name;
+      if (!verified) throw new Error('Runtime ownership could not be verified; files were preserved.');
+      owned.push(runtime);
+    }
+  }
+  const pointer = join(root, 'runtime.json');
+  let removePointer = false;
+  if (existsSync(pointer)) {
+    let current;
+    try { current = JSON.parse(readFileSync(pointer, 'utf8')); }
+    catch { throw new Error('Runtime selection metadata is unreadable; runtimes were preserved. Run setup to repair it.'); }
+    removePointer = /^[a-f0-9]{64}$/.test(current.identity) && owned.includes(join(directory, current.identity));
+  }
+  // All candidates are checked before deletion; never remove the campus data root.
+  for (const runtime of owned) await rm(runtime, { recursive: true });
+  if (existsSync(directory) && readdirSync(directory).length === 0) await rmdir(directory);
+  if (removePointer) await rm(pointer);
+  const uv = join(root, process.platform === 'win32' ? 'uv.exe' : 'uv');
+  const uvOwner = join(root, 'uv-owner.json');
+  if (existsSync(uvOwner) && existsSync(uv)) {
+    const expected = JSON.parse(readFileSync(uvOwner, 'utf8')).sha256;
+    if (!lstatSync(uv).isSymbolicLink() && createHash('sha256').update(readFileSync(uv)).digest('hex') === expected) {
+      await rm(uv); await rm(uvOwner);
+    } else console.error('Modified bootstrap cache was preserved for local review.');
+  }
+  const leases = join(root, 'runtime-leases');
+  if (existsSync(leases) && !lstatSync(leases).isSymbolicLink()) {
+    for (const name of readdirSync(leases)) {
+      const lock = join(leases, name);
+      if (/^[a-f0-9]{32}\.lock$/.test(name) && !lstatSync(lock).isSymbolicLink()) await rm(lock);
+    }
+    if (readdirSync(leases).length === 0) await rmdir(leases);
+  }
+  await rm(join(root, 'runtime-removal.pending'), { force: true });
+  console.log(`Removed ${owned.length} managed runtime(s). Saved user data was retained.`);
 }

package/npm/tum-mcp.mjs

@@ -1,21 +1,58 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
-import { currentPython, ensureRuntime } from './runtime.mjs';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { acquireSetupLock, currentPython, dataRoot, ensureRuntime, removeRuntimeFiles } from './runtime.mjs';
+import { managePackage } from './package-manager.mjs';
 
-const args = process.argv.slice(2);
+let args = process.argv.slice(2);
+const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 try {
   if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]))) {
-    console.log('TUM MCP 0.5.0\nCommands: setup [--client codex|claude|cursor|antigravity|generic], connect, scope, discover, status, doctor [--json] [--live], serve, skills, workspace, actions, logout, uninstall, update\nRun connect without arguments to select services and an installed Chromium browser. Run setup explicitly to provision the managed Python backend.');
+    console.log(`TUM MCP ${version}\nCommands: setup [--client codex|claude|cursor|antigravity|generic], connect, scope, discover, status, doctor [--json] [--live], serve, skills, study, logout, uninstall, update\nRun connect without arguments to select services and an installed Chromium browser. Run setup explicitly to provision the managed Python backend.`);
   } else if (['--version', 'version'].includes(args[0])) {
-    console.log('0.5.0');
+    console.log(version);
+  } else if (['setup', 'update', 'uninstall'].includes(args[0]) && args.some(arg => ['--help', '-h'].includes(arg))) {
+    const help = {
+      update: 'Usage: tum-mcp update [--local]\nInstall the latest npm release and refresh configured clients.\n--local refreshes this installed version without contacting npm.',
+      setup: 'Usage: tum-mcp setup [--client codex|claude|cursor|antigravity|generic] [--host local|windows]\nProvision the managed runtime and register explicitly selected clients.',
+      uninstall: 'Usage: tum-mcp uninstall [--all] [--purge-runtime] [--forget-credentials]\nRemove managed client setup and this npm installation. Saved data is retained by default.\n--client NAME removes one client only. --keep-package keeps npm installed.',
+    };
+    console.log(help[args[0]]);
   } else {
-    const setup = ['setup', 'update'].includes(args[0]);
-    const python = setup ? await ensureRuntime() : currentPython();
-    if (!python) throw new Error('SETUP_REQUIRED: Run tum-mcp setup first.');
-    const forwarded = args[0] === 'update' ? ['status'] : args;
-    const env = { ...process.env }; delete env.PYTHONPATH; delete env.PYTHONHOME;
-    const child = spawnSync(python, ['-I', '-m', 'tum_mcp', ...forwarded], { env, stdio: 'inherit', shell: false });
-    if (child.error) throw new Error('Managed backend could not start; run setup again.');
-    process.exitCode = child.status ?? 1;
+    let packageAction = args[0] === 'update';
+    if (args[0] === 'update') {
+      if (args.length > 2 || (args.length === 2 && args[1] !== '--local')) throw new Error('Usage: tum-mcp update [--local]. Use --help for details.');
+      if (args[1] === '--local') { packageAction = false; args = ['update']; }
+    }
+    if (args[0] === 'uninstall') {
+      const { values } = parseArgs({ args: args.slice(1), options: {
+        all: { type: 'boolean' }, client: { type: 'string' }, host: { type: 'string' },
+        'keep-package': { type: 'boolean' }, 'purge-runtime': { type: 'boolean' }, 'forget-credentials': { type: 'boolean' },
+      } });
+      if (values.host && !['local', 'windows'].includes(values.host)) throw new Error('Choose --host local or windows.');
+      if (values.client !== undefined && !['codex', 'claude', 'cursor', 'antigravity', 'generic'].includes(values.client)) throw new Error('Choose a supported --client name.');
+      if (values.client && (values.all || values['purge-runtime'] || values['forget-credentials'])) throw new Error('Client-only removal cannot use --all or data/runtime cleanup options.');
+      if (!values.client && !values.all) args.push('--all');
+      packageAction = !values.client && !values['keep-package'];
+      args = args.filter(arg => arg !== '--keep-package');
+    }
+    if (packageAction) {
+      process.exitCode = await managePackage(args[0], args.slice(1), dataRoot());
+    } else {
+      let python = ['setup', 'update'].includes(args[0]) ? await ensureRuntime() : currentPython();
+      if (args[0] === 'uninstall' && !python) python = await ensureRuntime();
+      if (!python) throw new Error('SETUP_REQUIRED: Run tum-mcp setup first.');
+      const forwarded = args;
+      const env = { ...process.env, TUM_MCP_NPM_LAUNCHER: '1' }; delete env.PYTHONPATH; delete env.PYTHONHOME;
+      const purge = args[0] === 'uninstall' && args.includes('--purge-runtime');
+      const release = purge ? await acquireSetupLock() : null;
+      try {
+        const child = spawnSync(python, ['-I', '-m', 'tum_mcp', ...forwarded], { env, stdio: 'inherit', shell: false });
+        if (child.error) throw new Error('Managed backend could not start; run setup again.');
+        process.exitCode = child.status ?? (child.signal === 'SIGINT' ? 130 : 1);
+        if (purge && child.status === 0) await removeRuntimeFiles();
+      } finally { if (release) await release(); }
+    }
   }
 } catch (error) { console.error(error.message); process.exitCode = 2; }

package/package.json

@@ -1,16 +1,59 @@
 {
   "name": "@jamestesting888/tum-mcp",
-  "version": "0.5.0",
-  "description": "Local-first TUM Moodle, Artemis, and Zulip integration with campus workflow skills",
+  "version": "0.6.1",
+  "description": "Read-only TUM Moodle, Artemis and Zulip integration with source-backed study workflows",
   "license": "MIT",
   "type": "module",
-  "bin": {"tum-mcp": "npm/tum-mcp.mjs"},
-  "engines": {"node": ">=22.14.0"},
-  "files": ["npm/tum-mcp.mjs", "npm/runtime.mjs", "npm/download.mjs", "npm/uv-artifacts.json", "npm/backend/*.whl", "npm/backend/requirements.txt", "npm/backend/manifest.json", "LICENSE", "NOTICE", "README.md", "docs/setup.md", "docs/development.md", "docs/tum-mcp.md"],
-  "scripts": {"prepack": "node npm/build.mjs", "test": "node --test npm/test/*.test.mjs", "test:consumer": "node npm/smoke-consumer.mjs"},
-  "publishConfig": {"access": "public"},
-  "repository": {"type": "git", "url": "git+https://github.com/jamestesting0/tum-mcp.git"},
+  "bin": {
+    "tum-mcp": "npm/tum-mcp.mjs"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "files": [
+    "npm/tum-mcp.mjs",
+    "npm/runtime.mjs",
+    "npm/download.mjs",
+    "npm/lock.mjs",
+    "npm/npm-command.mjs",
+    "npm/package-manager.mjs",
+    "npm/uv-artifacts.json",
+    "npm/backend/*.whl",
+    "npm/backend/requirements.txt",
+    "npm/backend/manifest.json",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "README.md",
+    "docs/setup.md",
+    "docs/development.md",
+    "docs/tum-mcp.md",
+    "docs/study.md"
+  ],
+  "scripts": {
+    "prepack": "node npm/build.mjs",
+    "test": "node --test npm/test/*.test.mjs",
+    "test:consumer": "node npm/smoke-consumer.mjs",
+    "test:upgrade": "node npm/upgrade-consumer.mjs",
+    "test:package-lifecycle": "node npm/package-consumer.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamestesting0/tum-mcp.git"
+  },
   "homepage": "https://github.com/jamestesting0/tum-mcp#readme",
-  "bugs": {"url": "https://github.com/jamestesting0/tum-mcp/issues"},
-  "keywords": ["mcp", "tum", "moodle", "artemis", "zulip", "codex"]
+  "bugs": {
+    "url": "https://github.com/jamestesting0/tum-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "tum",
+    "moodle",
+    "artemis",
+    "zulip",
+    "codex"
+  ]
 }