@jamestesting888/tum-mcp 0.4.1 → 0.6.0

package/npm/runtime.mjs

@@ -1,96 +1,244 @@
 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 { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+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, hostname } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { download } from './download.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 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.');
+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;
 }
 
+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 async function acquireSetupLock() {
+  const lock = join(dataRoot(), 'setup.lock');
+  const owner = { pid: process.pid, host: hostname(), nonce: randomUUID() };
+  const guard = join(dataRoot(), 'setup.claim');
+  try { await mkdir(guard, { mode: 0o700 }); }
+  catch { throw new Error('Another setup is claiming the lock. Retry; an interrupted setup.claim needs local review.'); }
+  try {
+  try { await mkdir(lock, { mode: 0o700 }); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    let previous;
+    try { previous = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')); }
+    catch { throw new Error('Setup lock has no readable owner. Confirm no setup is running before removing setup.lock.'); }
+    if (!Number.isSafeInteger(previous.pid) || previous.pid <= 0 || previous.host !== hostname()) {
+      throw new Error('Setup lock belongs to an unknown owner; preserve it for local review.');
+    }
+    let alive = true;
+    try { process.kill(previous.pid, 0); }
+    catch (failure) { if (failure.code === 'ESRCH') alive = false; }
+    if (alive) throw new Error('Another setup is running; retry when it finishes.');
+    const abandoned = `${lock}.${randomUUID()}.abandoned`;
+    await rename(lock, abandoned);
+    await rm(abandoned, { recursive: true, force: true });
+    try { await mkdir(lock, { mode: 0o700 }); }
+    catch { throw new Error('Another setup acquired the lock; retry when it finishes.'); }
+  }
+  await atomicWrite(join(lock, 'owner.json'), JSON.stringify(owner));
+  } finally { await rmdir(guard); }
+  return async () => {
+    const current = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+    if (current.nonce !== owner.nonce) throw new Error('Setup lock ownership changed; it was preserved.');
+    await rm(lock, { recursive: true, force: true });
+  };
+}
+
 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,33 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
-import { currentPython, ensureRuntime } from './runtime.mjs';
+import { readFileSync } from 'node:fs';
+import { acquireSetupLock, currentPython, ensureRuntime, removeRuntimeFiles } from './runtime.mjs';
 
 const 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.4.1\nCommands: setup [--client codex|claude|generic], connect, scope, discover, status, doctor, serve, skills, workspace, actions, logout, uninstall, update\nRun 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.4.1');
+    console.log(version);
+  } else if (['setup', 'update'].includes(args[0]) && args.length === 2 && ['--help', '-h'].includes(args[1])) {
+    console.log(args[0] === 'update'
+      ? 'Usage: tum-mcp update\nRefresh previously configured clients for the installed npm version.\nDownload a newer version first: npm install --global @jamestesting888/tum-mcp@latest'
+      : 'Usage: tum-mcp setup [--client codex|claude|cursor|antigravity|generic] [--host local|windows]\nProvision the managed runtime and register explicitly selected clients.');
   } else {
+    if (args[0] === 'update' && args.length !== 1) throw new Error('Usage: tum-mcp update (no arguments). Use --help for the update workflow.');
     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;
+    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,55 @@
 {
   "name": "@jamestesting888/tum-mcp",
-  "version": "0.4.1",
-  "description": "Local-first TUM Moodle, Artemis, and Zulip integration with campus workflow skills",
+  "version": "0.6.0",
+  "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", "docs/credential-storage-options.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-moodle-integration.git"},
-  "homepage": "https://github.com/jamestesting0/tum-moodle-integration#readme",
-  "bugs": {"url": "https://github.com/jamestesting0/tum-moodle-integration/issues"},
-  "keywords": ["mcp", "tum", "moodle", "artemis", "zulip", "codex"]
+  "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",
+    "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"
+  },
+  "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"
+  ]
 }

package/docs/credential-storage-options.md

@@ -1,86 +0,0 @@
-# Credential storage and setup experience
-
-Checked against project code and primary upstream documentation on 24 October 2026.
-
-## What other projects do
-
-| Project | Protected default | File alternative and trade-off |
-| --- | --- | --- |
-| [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/credstores.md) | macOS Keychain and Windows Credential Manager; configurable Linux stores | Supports Windows DPAPI-protected files. Also offers explicitly insecure plaintext files and an ephemeral cache. |
-| [Docker](https://docs.docker.com/reference/cli/docker/login/#credential-stores) | Native credential helpers; Docker Desktop configures one | Without a helper it stores base64-encoded credentials in configuration. Docker describes that as less secure. |
-| [GitHub CLI](https://cli.github.com/manual/gh_auth_login) | System credential store | Supports `--insecure-storage` and documents a plain-file fallback when secure storage fails. [Its implementation](https://github.com/cli/cli/blob/trunk/internal/config/config.go#L496-L512) explicitly tracks whether insecure storage was used. |
-| [Electron](https://www.electronjs.org/docs/latest/api/safe-storage) | macOS Keychain; Windows DPAPI; Linux desktop secret stores | macOS can still prompt. Its documentation recommends consistent code signing to prevent repeated approval after updates. Linux fallback backends need careful inspection because protection can be weaker. |
-
-Saving a key elsewhere is technically possible, but location alone does not
-protect it. A readable key file next to encrypted sessions lets a process that
-can copy both decrypt the sessions. Restrictive file permissions help against
-other OS users; they do not provide a separate secret-store boundary against
-code running as the same user. This is why the protected defaults above still
-use operating-system services.
-
-## Current TUM MCP implementation
-
-| Platform | Implemented storage | Verification and expected setup |
-| --- | --- | --- |
-| macOS | Native Keychain item holds the encryption key; service cookies remain in encrypted files | Real saved sessions and scoped reads passed from the managed runtime after the user approved access. OS prompts remain possible for locked items, changed application identity, or temporary approval. |
-| Windows | Windows Credential Locker through Python keyring | Implementation and CI configuration exist. Hands-on Windows verification is still pending; no claim of universally prompt-free operation is made. |
-| Linux | Freedesktop Secret Service through Python keyring | ARM64 and x86_64 container bootstrap passed. On x86_64, an encrypted credential round trip across separate processes passed through real GNOME Secret Service in an isolated D-Bus session. Real desktop browser sign-in remains open. A usable, unlocked service and D-Bus session are required. |
-
-The backend selection is in `tum_moodle.auth.system_keyring`; encryption and
-account binding are in `tum_mcp.credentials.Vault`. There is no automatic
-plaintext fallback. The data-encryption key's service name and storage location
-are stable across backend-wheel updates.
-
-Windows can also protect a file directly with per-user
-[DPAPI](https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata).
-That avoids an adjacent unprotected key file. It is a reasonable optional backend
-if Credential Manager proves unsuitable, but it is not implemented in this build.
-It does not remove the need for a usable Windows user/logon context.
-
-## Why this setup prompted repeatedly
-
-The initial account connection ran under development Python. The installed
-package then used managed Python to access the same existing Keychain item.
-Those were different requesting executables. Python keyring documents that
-access is associated with the
-[Python executable](https://keyring.readthedocs.io/en/stable/#security-considerations).
-Temporary **Allow** and persistent **Always Allow** are also different choices.
-
-The fresh-install path was tested separately with a disposable native Keychain
-item: managed Python created it, then a second process of that same runtime read
-it successfully in about one second without another user interaction. The item
-was deleted afterward. This supports using the installed runtime from the first
-login; it does not guarantee every Mac policy will suppress all prompts.
-
-A subsequent real MCP check passed through the installed Codex plugin, its Node
-launcher, and managed Python: both provider identities verified, the selected
-Zulip channel was readable, and an unselected channel was denied. No remote
-submission or message write was performed.
-
-## Recommended direction
-
-1. Keep native protected storage as the default and use the installed `tum-mcp`
-   command for both onboarding and normal use.
-2. Add a foreground storage-access check before opening browser login, so any
-   necessary OS approval happens during setup rather than a later tool call.
-   This is a proposed UX improvement, not a shipped behavior change here.
-3. If future macOS interpreter updates keep changing identity, use a dedicated,
-   consistently signed credential helper. That needs separate packaging/signing
-   work and cannot guarantee that first-time OS approval never appears.
-4. Consider explicit DPAPI-file or session-only modes for their appropriate
-   platforms/use cases. Plain-file storage should require an informed choice;
-   session-only storage requires signing in again after the broker stops.
-
-These recommendations change neither the existing stored credentials nor their
-permissions. Keychain approval is scoped to Python's access to this item; scripts
-using the same trusted executable can also request it. A restricted MCP API is
-not a system-wide sandbox for an otherwise unrestricted coding agent.
-
-## Separate desktop-app permission
-
-The macOS prompt naming **ChatGPT** and asking to access data from other apps is
-separate from a Keychain request for `tum-mcp`. Apple associates that prompt with
-[files in other apps' sandbox containers](https://developer.apple.com/documentation/BundleResources/Information-Property-List/NSAppDataUsageDescription).
-The campus backend's default storage and HTTP read paths do not need that broad
-host permission. The specific container behind the observed prompt was not
-identified; computer-use inventory is a possible trigger, not a confirmed cause.