@jamestesting888/tum-mcp 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changes
 
+## 0.6.1 — 2026-10-25
+
+- Make `tum-mcp update` download and validate the latest npm release before
+  replacing the invoked installation and refreshing configured clients.
+  Preserve newer installed versions; `--local` refreshes without contacting npm.
+- Make `tum-mcp uninstall` remove managed client setup and the npm package in
+  one command. Keep saved data by default; stop package removal on conflicts.
+  Client-only removal retains npm, and `--keep-package` supports managed cleanup.
+- Run npm through Node on all platforms, serialize package operations, and use
+  an external worker while Windows replaces package files.
+- Test actual global installations against a private synthetic registry, including
+  failed downloads/preparation/replacement, customized files, and data preservation.
+
 ## 0.6.0 — 2026-10-25
 
 - Merge course setup and updates into `sync-study`, with recovery for incomplete
@@ -20,8 +33,8 @@
   Reuse isolated test fixtures,
   retain native/platform coverage and expose slow tests and failures in CI.
 - Preserve Windows CRLF study instructions through repeated synchronization.
-- Group Artemis and Zulip implementation by provider, retaining read-only campus
-  tools and Moodle compatibility. Fix OCR with aliased macOS temporary paths.
+- Group Artemis and Zulip implementation by provider, retaining read-only
+  course tools. Fix OCR with aliased macOS temporary paths.
 
 Upgrading does not rebuild personal study sites automatically. Ask your agent to
 update the prepared website; customized renderer files are preserved for review.

package/README.md

@@ -3,7 +3,7 @@
 Connect your coding agent to Moodle, Artemis and Zulip. Read course content and
 build a private, source-backed study workspace. Unofficial; independent of TUM.
 
-**Latest release: [0.6.0](https://www.npmjs.com/package/@jamestesting888/tum-mcp).**
+**Latest release: [0.6.1](https://www.npmjs.com/package/@jamestesting888/tum-mcp).**
 [Release notes](CHANGELOG.md).
 
 ## Agent setup
@@ -36,13 +36,9 @@ Select services with **Space**, then **Enter**. Choose an installed browser and
 complete sign-in there. Only selected tabs open; Zulip needs no API key.
 Enable the [course and channel scopes](docs/tum-mcp.md#connections-and-scopes) you want to use.
 
-| Client | Setup |
-| --- | --- |
-| Codex | `--client codex` · plugin and skills; enable/restart when prompted |
-| Claude Code | `--client claude` · MCP registration and skills |
-| Cursor | `--client cursor` · MCP registration and all five skills; restart |
-| Google Antigravity | `--client antigravity` · MCP registration and all five skills; restart |
-| Other MCP clients | `--client generic` · configuration for manual installation |
+Choose a client with `--client`: `codex`, `claude`, `cursor` or `antigravity`.
+Setup configures MCP and installs all five skills; follow any activation or
+restart prompts. Use `generic` for manual MCP setup.
 
 For existing Cursor and Antigravity setups, run `tum-mcp update` to add the skills.
 Updates and uninstall preserve customized files and report them for review.
@@ -51,7 +47,7 @@ Supports macOS, Windows, glibc Linux x86_64/ARM64 and WSL 3.x. In WSL, sign-in
 opens a Windows browser. Add `--host windows` to setup for a Windows client that
 uses the WSL backend. [Browser and WSL setup](docs/setup.md#wsl).
 
-Setup supplies a private Python runtime. New connections use encrypted local
+Setup supplies a private Python runtime. Connections use encrypted local
 files and need no native keyring, Git or Docker.
 
 ## Read and study
@@ -167,11 +163,13 @@ stay local. Study progress is saved in your browser.
 ## Update
 
 ```sh
-npm install --global @jamestesting888/tum-mcp@latest
 tum-mcp update
 ```
 
-`update` prepares the invoked package's runtime and refreshes configured clients.
+`update` downloads the latest release, validates its backend, installs it in the
+same npm location and refreshes configured clients. It never downgrades a newer
+installation. Use `tum-mcp update --local` to refresh the installed version without checking npm.
+From 0.6.0 or earlier, upgrade the npm package once to obtain this command.
 Sessions, scopes and downloads carry forward. User-edited entries and skills are
 preserved and reported for review. Reload the client; refresh its cached plugin
 if needed. Study sites are updated separately through the study workflows.
@@ -179,14 +177,14 @@ if needed. Study sites are updated separately through the study workflows.
 ## Remove
 
 ```sh
-tum-mcp uninstall --all
-npm uninstall --global @jamestesting888/tum-mcp
+tum-mcp uninstall
 ```
 
-Managed registrations and unchanged skills are removed. Settings, sessions,
+The npm package, managed registrations and unchanged skills are removed. Settings, sessions,
 downloads and study projects are preserved. After closing clients, add
 `--purge-runtime` to remove generated runtimes or `--forget-credentials` to
-remove saved local sessions and historical Git tokens. [Removal details](docs/setup.md#update-and-remove).
+remove saved local credentials. [Removal details](docs/setup.md#update-and-remove).
+Use `--client NAME` to remove just one client, or `--keep-package` to retain npm.
 
 [Guide](docs/tum-mcp.md) · [Setup](docs/setup.md) · [Study workflows](docs/study.md) · [Development](docs/development.md)
 

package/docs/development.md

@@ -2,8 +2,6 @@
 
 The npm package is the distribution. Its wheel contains one Python package,
 `src/tum_mcp/`, with peer `moodle/`, `artemis/` and `zulip/` provider packages.
-The retired standalone Moodle plugin and its checkout installer are no longer
-maintained.
 Client adapters still generate the configuration each host needs.
 
 ## Checks
@@ -19,6 +17,7 @@ npm test
 npm pack --ignore-scripts --pack-destination dist
 npm run test:consumer
 npm run test:upgrade
+npm run test:package-lifecycle
 ```
 
 Python 3.13 is the managed runtime. Install Tesseract for OCR tests. Default tests
@@ -57,8 +56,11 @@ CI runs macOS, Windows and Linux, plus both distribution engines on WSL 3.x.
 Consumer checks install the actual npm artifact, discover tools, build a study
 site and test available Chromium browsers with temporary profiles and synthetic
 pages. WSL verifies Windows browser transport. No live account is used.
-Upgrade checks cover public 0.4.1/0.5.0, client refresh, customized-file conflicts,
+Upgrade checks cover public 0.6.0, client refresh, customized-file conflicts,
 failed preparation, runtime repair and removal that preserves work/credentials.
+The package-lifecycle check uses a local synthetic registry and real isolated
+global npm prefixes to verify downloads, backend validation, replacement,
+failure ordering and one-command removal. It does not publish a test release.
 All five jobs must pass on the exact pushed commit before completion is claimed.
 
 Live Moodle checks are opt-in: `TUM_MOODLE_LIVE=1 uv run pytest tests/live -q`.
@@ -97,14 +99,7 @@ tag and artifact integrity before pushing the release documentation.
 
 Client setup installs managed copies of the repository's skills; those copies are
 outputs, not another source tree. Use `skills customize` for a personal override.
-The Codex adapter generates a small host plugin because that client uses it to
-load skills and MCP together; it is separate from the removed top-level Moodle
-plugin distribution.
-
-Keep Moodle's existing native-store service/account identity, session paths and
-download locations stable during migrations. Environment variable names and the
-`tum-moodle` CLI alias remain compatible; its implementation now resides inside
-`tum_mcp.moodle`. No automatic native-store secret extraction occurs.
+The Codex adapter generates a small host plugin to load skills and MCP together.
 
 Extraction uses bounded subprocesses. POSIX enforces CPU/process-group limits;
 Windows terminates the worker and observed children. Study imports and preview

package/docs/setup.md

@@ -35,11 +35,10 @@ Run **`tum-mcp connect`**, with no arguments, in an interactive terminal:
 3. Complete TUM sign-in/MFA in the opened window. Only selected service tabs open.
 4. Return to the terminal for the saved-connection result.
 
-Moodle uses exactly the same selector and storage flow as Artemis and Zulip.
-No API key or Keychain prompt is needed. A temporary browser profile keeps the
-connection separate from your everyday browser. Ctrl+C closes it and preserves
+All three services use the same sign-in and encrypted session storage flow.
+No API key or native credential-store prompt is needed. A temporary browser
+profile keeps the connection separate from your everyday browser. Ctrl+C closes it and preserves
 connections that already completed. A dumb terminal uses numbered prompts.
-Old service arguments and `--service`/`--auth` flags are no longer accepted.
 
 Chrome, Edge, Brave, Chromium, Vivaldi and Opera are detected in their standard
 locations. Selected preview channels and Opera GX are detected where installed.
@@ -113,19 +112,25 @@ browser discovery still requires functioning interop.
 Sessions are encrypted with owner-restricted local key files. This avoids native
 credential-store prompts, but anyone obtaining both key and ciphertext can
 decrypt them. [Storage locations and recovery](tum-mcp.md#connections-and-scopes)
-explain migration and backup. Existing Moodle data and downloads are preserved.
+explain where sessions are saved and how to back them up.
 
 ## Update and remove
 
 ```sh
-npm install --global @jamestesting888/tum-mcp@latest
 tum-mcp update
 ```
 
-`update` activates the backend bundled in the invoked npm package and refreshes
-previously configured clients. It does not fetch a newer npm version itself,
-connect services, change scopes or register additional clients. `setup --client
-NAME` explicitly registers one client and can also refresh that client's managed
+From 0.6.1, `update` retrieves the latest npm release, validates its backend in a
+temporary installation, replaces the invoked package and refreshes previously
+configured clients. It preserves the installation prefix and global/local mode.
+It does not connect services, change scopes or register additional clients.
+It never downgrades a newer installation. `update --local` skips npm and repairs
+or refreshes the installed version. Source/pinned builds use this local mode;
+temporary npx and linked source installations are not replaced automatically.
+Automatic replacement also stops if the package directory contains configured
+sessions, downloads or course work; move that data outside the package first.
+For 0.6.0 and earlier, first install the newer npm package once.
+`setup --client NAME` explicitly registers one client and can also refresh that client's managed
 files. WSL Windows registrations keep their distribution/user/data paths.
 
 Ownership receipts track the entries and files installed by TUM MCP. Unchanged
@@ -138,57 +143,40 @@ not selected, and a damaged runtime is repaired into a fresh generation. A newer
 managed client is not silently downgraded by an older package; intentional
 rollback starts by unregistering that client, then registering the reviewed version.
 
-0.4.1/0.5.0 installations without receipts are adopted only after matching their
-retained runtime's canonical client output. The seven former workflow skills and the three website skills are replaced by
-`read-content`, `sync-study` and `prepare-study`; `audio-notes` adds
-spoken lessons derived from the prepared website. Personal overrides
-under retired names remain in the config `skills/` directory; review and merge
-retrieval guidance into `read-content` before exporting a replacement pack.
 Reload MCP servers in Cursor/Antigravity, restart Claude as appropriate, and
 update/reinstall TUM MCP from the personal source in Codex Plugins if its cached
 copy still shows the older skills. Writing source files does not activate a host.
 
 Remove a single client with `tum-mcp uninstall --client cursor` (replace the
 client as needed; add `--host windows` from WSL for a Windows client). To remove
-all managed registrations before uninstalling npm:
+the npm package and all managed registrations:
 
 ```sh
-tum-mcp uninstall --all
-npm uninstall --global @jamestesting888/tum-mcp
+tum-mcp uninstall
 ```
 
 Custom edits and user-added files are preserved. Codex's local source/catalog
 entry can be removed, but its cached/active plugin must also be removed or
-disabled through Codex Plugins. No npm uninstall hook deletes user data.
+disabled through Codex Plugins. Package removal runs only after successful
+client cleanup; conflicts preserve npm so you can review and retry. `--all`
+is accepted explicitly, and `--keep-package` removes client setup without npm.
+No npm lifecycle hook performs cleanup or reads credentials.
 
 For explicit cleanup, **close coding clients first**, then run:
 
 ```sh
-tum-mcp uninstall --all --purge-runtime --forget-credentials
-npm uninstall --global @jamestesting888/tum-mcp
+tum-mcp uninstall --purge-runtime --forget-credentials
 ```
 
 `--purge-runtime` deletes verified managed runtime generations after the Python
 helper exits, and removes unchanged managed bootstrap/browser-driver caches.
 Active tracked backends or unrecognized runtime files stop automatic removal.
 Paths overlapping configured assignment work, downloads or Moodle data are
-protected. `--forget-credentials` removes local encrypted service sessions, keys
-and participation Git tokens; it does not revoke remote credentials. Native
-Keychain/Credential Manager/Secret Service records and legacy Moodle sessions
-stay intact. Settings, custom skills, course cache, downloads and assignment
-work are retained by these commands. No command recursively deletes the campus
+protected. `--forget-credentials` removes saved local credentials and session
+keys; it does not revoke remote credentials. Settings, custom skills, course
+cache, downloads and assignment work are retained by these commands.
+No command recursively deletes the campus
 data root. Course audio and optional shared speech models/runtimes also remain.
 Remove a shared speech cache only when explicitly requested and no other course
 needs it; its host paths are documented in the audio skill. If removal is
-interrupted, run npm `setup` to recover before reuse.
-
-## Existing Moodle-only installations
-
-The older `tum-moodle` commands and sixteen `moodle_*` tools remain compatible.
-The separate source/plugin installer retains its original native credential
-store: macOS Keychain, Windows Credential Manager, or Linux Secret Service.
-Its native-store identity, existing session paths and downloads remain intact.
-The combined `tum-mcp serve` uses local-file storage and directs all login
-requests to `tum-mcp connect`. Reconnect once through that selector to create the
-new session; no automatic extraction of older native-store secrets occurs.
-Disable the older plugin when activating TUM MCP to avoid duplicate tools.
+interrupted, run `tum-mcp setup --client NAME` to recover before reuse.

package/docs/tum-mcp.md

@@ -1,19 +1,19 @@
 # TUM MCP guide
 
 Package: `@jamestesting888/tum-mcp`, CLI: `tum-mcp`, backend: Python 3.13.
-Version **0.6.0** provides read-only course retrieval and five local study workflows.
+Development version **0.6.1 (unreleased)** adds npm package management to the
+read-only course retrieval and five local study workflows in 0.6.0.
 
 ## Current capabilities
 
-All sixteen `moodle_*` compatibility tools remain available, including materials,
-announcements, forums and explicitly scoped private-record reads. Artemis adds
+The sixteen `moodle_*` tools provide materials, announcements, forums and
+explicitly scoped private-record reads. Artemis adds
 available-course metadata, lectures and learning units, student PDF attachments,
 released non-quiz statements and permitted exact-commit feedback. Zulip provides
 scoped channel/topic search and cited discussion reads.
 
 Website access is read-only. There are no public exercise workspace, test-run,
-submission, start, deployment, rebuild or push workflows. The retained internal
-remote gate rejects every action even if an old verification flag is enabled.
+submission, start, deployment, rebuild or push workflows.
 Local downloads, source inventories, study-site builds and checkpoint storage
 are local operations; they do not post, submit or mark campus content as read.
 
@@ -67,22 +67,19 @@ and Python 3.13.15; an existing matching uv, including the verified cached downl
 is reused. Source checkouts and system
 Python are unnecessary for consumers. Supported bootstrap targets are macOS
 arm64/x64, Windows arm64/x64, and glibc Linux arm64/x64; hands-on verification is
-recorded separately. New campus sessions use permission-restricted local keys and need no Secret Service.
-Clean consumer bootstrap, idempotent setup, diagnostics, and skill validation
-passed on macOS ARM64 and in Linux ARM64 and x86_64 containers. The x86_64 check
-ran through Docker amd64 emulation on an ARM64 Mac; packaged MCP protocol checks
-and an encrypted credential round trip through a real GNOME Secret Service in an
-isolated D-Bus session also passed. Real Linux desktop browser sign-in, macOS x64,
-and Windows hands-on checks remain open. New storage and terminal behavior need
-the current checkout’s test evidence; earlier native-store results do not certify them. The installer targets glibc Linux
-x86_64/amd64 and aarch64/ARM64.
-
-`update` prepares the backend bundled in the invoked package, refreshes
-previously configured clients and preserves older runtime generations.
+recorded separately. Campus sessions use permission-restricted local keys.
+CI checks clean installation, updates, removal, MCP discovery and synthetic
+browser workflows on macOS, Windows, Linux and both WSL engines. See the
+[development guide](development.md#checks) for the verification layers.
+
+`update` downloads and validates the latest release, replaces the invoked npm
+installation and refreshes previously configured clients. `update --local`
+refreshes the installed version without npm. Retained runtimes keep pinned
+clients working, and newer installed versions are not silently downgraded.
 [Update and removal behavior](setup.md#update-and-remove) covers ownership
-receipts, legacy adoption, conflict handling and explicit cleanup. To obtain a newer public package after publication,
-invoke its reviewed version explicitly. It does not publish a release or replace
-customized client skills silently. If interrupted setup leaves `setup.lock`,
+receipts, conflict handling and explicit cleanup. `uninstall` removes managed
+clients and npm; `--client NAME` or `--keep-package` retains the package.
+Customized files and saved data are preserved. If interrupted setup leaves `setup.lock`,
 confirm that no setup process is running before removing that directory locally.
 An invalid or incomplete runtime is never selected for serving. Failed validation
 clears its ready marker so explicit setup can rebuild it; older runtimes remain
@@ -108,10 +105,9 @@ tum-mcp scope zulip ACCOUNT_ID --channel CHANNEL_ID
 `connect` takes no arguments or connection options. Move with up/down, toggle
 services with Space, and press Enter. Choose a browser when more than one is
 installed. Only selected tabs open in one temporary browser context. Moodle,
-Artemis and Zulip all follow this flow; no separate Moodle login is needed.
+Artemis and Zulip all follow this flow.
 Sign-in/MFA stays in the browser. `TERM=dumb` uses numbered prompts. Ctrl+C
-cancels and retains completed connections. Old service/campus arguments and
-`--service`/`--auth` flags are rejected before any browser opens.
+cancels and retains completed connections.
 
 Detection covers Chrome, Edge, Brave, Chromium, Vivaldi, Opera and selected
 preview channels. Set `TUM_MCP_BROWSER` to an executable path for another
@@ -121,41 +117,30 @@ Only service-owned cookies are saved; identity-provider cookies are discarded
 when the temporary browser closes. Existing browser profiles are never imported.
 
 Zulip uses its read-only `/json/` routes with the browser session; no API key is
-required. Reconnect through the same selector when a session expires. Existing
-API-key records remain readable for compatibility, but key entry is not part of
-onboarding. See [Zulip's dispatcher](https://github.com/zulip/zulip/blob/12.0/zerver/lib/rest.py).
+required. Reconnect through the same selector when a session expires.
+See [Zulip's dispatcher](https://github.com/zulip/zulip/blob/12.0/zerver/lib/rest.py).
 Existing scopes survive reconnection; new identities start with empty scopes.
 Private Zulip channels require `--private-channel ID` as well as `--channel ID`.
 `--sensitive` enables own Artemis participation/feedback reads. It grants no
 website mutation or local execution permission.
 
 Settings live outside the installed package in `TUMMCP/config/preferences.json`.
-The default data directory is beside the legacy `TUMMoodle` directory on each OS.
-Existing Moodle data and its native-store identity are retained in place. New
-campus connections deliberately do not read or migrate native-store secrets;
-reconnect each service once to use local-file storage. The combined MCP process
-uses that storage for all `moodle_*` compatibility tools. The separate Moodle-only
-installer keeps its native-store default.
-Historical Git credentials remain local data for legacy cleanup; the current
-package provides no assignment Git workflow.
-
-New Moodle sessions live under `TUMMoodle/local-session/`; campus credentials live
-under `TUMMCP/credentials/local/`. Each directory has an independent `session.key`.
+Moodle sessions live under `TUMMoodle/local-session/`; Artemis and Zulip credentials
+live under `TUMMCP/credentials/local/`. Each directory has an independent `session.key`.
 Encrypted records and keys have owner-only permissions: 0700 directories / 0600
 keys on POSIX; protected current-user DACLs on Windows through PowerShell. No
-administrator privileges are requested. This avoids Keychain/Secret Service
+administrator privileges are requested. This avoids native credential-store
 prompts but protects less than a native store. A copy of both ciphertext and key
 is sufficient to decrypt a session. Do not share, sync publicly, or package them.
 
 Missing or damaged keys fail closed. Restore the matching key from a private
 backup. To start fresh, stop clients and move the affected **local storage folder**
-to a private backup before reconnecting; this also resets its stored Git tokens.
-Never remove the legacy Moodle directory or downloads to repair a login.
-Native-store records remain available to the older installation for rollback.
+to a private backup before reconnecting. Keep downloaded course materials when
+repairing a login.
 
 Zulip message text is retrieved live and is not persisted. Retrieved excerpts may
-be transmitted to the coding agent's configured AI provider. Moodle's existing
-document cache retains its documented plaintext/expiry behavior.
+be transmitted to the coding agent's configured AI provider. Moodle caches
+documents and extracted text locally in plaintext.
 
 Course nicknames can be mapped in `mappings` using explicit per-service IDs.
 The tools resolve one exact mapping; ambiguity never grants broader access.
@@ -191,11 +176,9 @@ progress are preserved during package updates/removal.
 ## Client and skill setup
 
 `setup --client codex` prepares a local plugin/marketplace entry using the
-portable Agent Plugins schemas. Enable it in
-Codex Plugins, restart, and verify real tool and skill loading. Disable the legacy
-TUM Moodle plugin when switching so duplicate tools/skills are not active.
-The old installation remains available for rollback. Setup reports required UI
-steps and never equates writing files with activation.
+portable Agent Plugins schemas. Enable it in Codex Plugins, restart, and verify
+real tool and skill loading. Setup reports required UI steps and never equates
+writing files with activation.
 
 The Codex adapter uses a contained Node launcher to pin the managed Python in
 isolated mode; portable stdio manifests require a bare or contained executable.
@@ -291,5 +274,5 @@ it is described as verified. Test data and public fixtures are synthetic. Real
 course material, local agent notes and screenshots stay under ignored local paths.
 Maintainer checks include a reviewed tarball inventory, integrity checks and an
 isolated consumer install. Never publish or stage npm packages as a test. Registry
-publication requires separate user authorization and remains paused for this work.
+publication is an explicit maintainer action.
 `tum-mcp status` reports registry state as `not_checked`; it reads local configuration.

package/npm/backend/manifest.json

@@ -1,5 +1,5 @@
 {
-  "wheel": "tum_mcp-0.6.0-py3-none-any.whl",
-  "wheelSha256": "8437422504920753d1d6781cd87c57065cfbb8c0630ff0c5fd1de237b2d00426",
+  "wheel": "tum_mcp-0.6.1-py3-none-any.whl",
+  "wheelSha256": "59ecf435716e6c0ab68ed9720f2c137b3236f64dd5e962db4c3bf82b76c45ba2",
   "requirementsSha256": "25f9efa7a4ffb0b97abcfeb9d4706d04808273ab1b35abcfaa1ef0b66e87591b"
 }

package/npm/lock.mjs

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { mkdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+
+export async function acquireLock(root, name = 'setup') {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const lock = join(root, `${name}.lock`);
+  const owner = { pid: process.pid, host: hostname(), nonce: randomUUID() };
+  const guard = join(root, `${name}.claim`);
+  try { await mkdir(guard, { mode: 0o700 }); }
+  catch { throw new Error(`Another ${name} is claiming the lock. Retry; an interrupted ${name}.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(`${name} lock has no readable owner. Confirm no operation is running before removing ${name}.lock.`); }
+      if (!Number.isSafeInteger(previous.pid) || previous.pid <= 0 || previous.host !== hostname()) {
+        throw new Error(`${name} 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 ${name} 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 ${name} acquired the lock; retry when it finishes.`); }
+    }
+    const temporary = join(lock, `${owner.nonce}.pending`);
+    await writeFile(temporary, JSON.stringify(owner), { mode: 0o600, flag: 'wx' });
+    await rename(temporary, join(lock, 'owner.json'));
+  } finally { await rmdir(guard); }
+  return async () => {
+    const current = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+    if (current.nonce !== owner.nonce) throw new Error(`${name} lock ownership changed; it was preserved.`);
+    await rm(lock, { recursive: true, force: true });
+  };
+}

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

@@ -2,10 +2,11 @@ import { spawnSync } from 'node:child_process';
 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 { homedir } from 'node:os';
 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'));
@@ -109,40 +110,7 @@ async function uvExecutable() {
   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 function acquireSetupLock() { return acquireLock(dataRoot()); }
 
 export async function ensureRuntime() {
   const backend = join(packageRoot, 'npm/backend');

package/npm/tum-mcp.mjs

@@ -1,33 +1,58 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { acquireSetupLock, currentPython, ensureRuntime, removeRuntimeFiles } from './runtime.mjs';
+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 ${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(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 (['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 {
-    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;
-    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(); }
+    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,6 +1,6 @@
 {
   "name": "@jamestesting888/tum-mcp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Read-only TUM Moodle, Artemis and Zulip integration with source-backed study workflows",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,9 @@
     "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",
@@ -31,7 +34,8 @@
     "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:upgrade": "node npm/upgrade-consumer.mjs",
+    "test:package-lifecycle": "node npm/package-consumer.mjs"
   },
   "publishConfig": {
     "access": "public"