unity-mcp-cli 0.87.0 → 0.89.0

package/dist/lib/install-extension.js

@@ -0,0 +1,182 @@
+import * as fs from 'fs';
+import { EXTENSIONS_CATALOG, findExtension, hasVersion, } from '../utils/extensions-catalog.js';
+import { addPackageToManifest, resolveLatestPackageVersion } from '../utils/manifest.js';
+import { silentLogger } from './logger.js';
+import { emitProgress } from './progress.js';
+import { requireUnityProject } from './validation.js';
+/**
+ * Install (or update) a Unity-MCP extension into a consumer Unity project, as a
+ * REAL installer that is behaviourally identical to the in-editor window's
+ * `ExtensionPanel`:
+ *
+ *  1. Resolve `extensionId` to a descriptor in the SHARED catalogue
+ *     (`Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/extensions.catalog.json`,
+ *     mirrored here by `EXTENSIONS_CATALOG`).
+ *  2. Validate that the target path hosts a Unity project (`Packages/manifest.json`).
+ *  3. Resolve the version to install: the explicit `version` override, else the
+ *     catalogue pin, else OpenUPM's `dist-tags.latest` fetched live. Every shipped
+ *     catalogue entry is unpinned, so the live fetch is the normal path.
+ *  4. Read-modify-write `Packages/manifest.json`: ensure the OpenUPM scoped registry
+ *     and its required scopes, then add or version-bump the package dependency.
+ *  5. Tell the caller Unity must resolve packages (the CLI cannot call
+ *     `UnityEditor.PackageManager.Client.Resolve()` — only the editor can).
+ *
+ * Library-safe: no stdout noise, no `process.exit`, no throws past the public
+ * boundary; returns a `{ kind: 'success' | 'failure' }` union. Idempotent: a re-run
+ * that finds the dependency at an equal-or-newer version reports
+ * `already-up-to-date` and makes no write. Mirrors `installPlugin`'s shape exactly
+ * so the app can adopt it the same way.
+ */
+export async function installExtension(opts) {
+    const warnings = [];
+    const nextSteps = [];
+    const extensionId = opts?.extensionId ?? '';
+    try {
+        const catalog = opts.catalog ?? EXTENSIONS_CATALOG;
+        const resolved = findExtension(extensionId, catalog);
+        if (resolved === null) {
+            return {
+                kind: 'failure',
+                success: false,
+                extensionId,
+                warnings,
+                nextSteps,
+                error: new Error(unknownExtensionMessage(extensionId, catalog)),
+            };
+        }
+        const validated = requireUnityProject(opts?.unityProjectPath);
+        if (!validated.ok) {
+            return {
+                kind: 'failure',
+                success: false,
+                extensionId,
+                packageId: resolved.packageId,
+                manifestPath: validated.manifestPath,
+                warnings,
+                nextSteps,
+                error: validated.error,
+            };
+        }
+        const { projectPath } = validated;
+        emitProgress(opts.onProgress, {
+            phase: 'start',
+            message: `Installing extension ${resolved.packageId} into ${projectPath}`,
+        });
+        // Apply the optional `version` override (drives both the pin written and, via
+        // `force`, whether a downgrade is permitted).
+        const descriptor = applyVersionOverride(resolved, opts.version, warnings);
+        const isExplicitVersion = (opts.version ?? '').trim() !== '';
+        let version;
+        if (hasVersion(descriptor)) {
+            // Non-null only for an explicit override or a (currently unused) catalogue pin.
+            version = descriptor.version;
+        }
+        else {
+            version = await resolveLatestPackageVersion(descriptor.packageId, silentLogger, '--extension-version');
+            emitProgress(opts.onProgress, {
+                phase: 'dependencies-resolved',
+                message: `Resolved latest ${descriptor.packageId} version: ${version}`,
+                version,
+            });
+        }
+        const before = readInstalledVersion(validated.manifestPath, descriptor.packageId);
+        const result = addPackageToManifest(projectPath, descriptor.packageId, version, isExplicitVersion, silentLogger);
+        // `addPackageToManifest` refuses to downgrade unless `force`; surface that as a
+        // warning rather than silently reporting the requested version.
+        if (result.resolvedVersion !== version && !isExplicitVersion) {
+            warnings.push(`${descriptor.packageId} is already at version ${result.resolvedVersion} (>= ${version}). ` +
+                'Skipping version update. Pass an explicit `version` to force a specific value.');
+        }
+        emitProgress(opts.onProgress, {
+            phase: 'manifest-patched',
+            message: result.modified
+                ? `Updated ${result.manifestPath}`
+                : 'manifest.json is already up to date.',
+            manifestPath: result.manifestPath,
+        });
+        // Derive the outcome from what was actually on disk before the write, NOT from
+        // `modified` alone: `modified` is also true when only the scoped registry had to
+        // be added, which is not an "added extension".
+        const outcome = before === null
+            ? 'added'
+            : result.resolvedVersion === before
+                ? 'already-up-to-date'
+                : 'updated';
+        const message = outcome === 'added'
+            ? `Added ${descriptor.packageId} ${result.resolvedVersion}. Unity will resolve the package on next focus.`
+            : outcome === 'updated'
+                ? `Updated ${descriptor.packageId} from ${before} to ${result.resolvedVersion}.`
+                : `${descriptor.name} is already installed and up to date (${result.resolvedVersion}).`;
+        if (outcome !== 'already-up-to-date') {
+            nextSteps.push('Open (or focus) the Unity Editor so the Package Manager resolves the new dependency.');
+        }
+        emitProgress(opts.onProgress, { phase: 'done', message: 'Extension install complete.' });
+        return {
+            kind: 'success',
+            success: true,
+            outcome,
+            changed: outcome !== 'already-up-to-date',
+            extensionId,
+            packageId: descriptor.packageId,
+            fromVersion: before,
+            toVersion: result.resolvedVersion,
+            manifestPath: result.manifestPath,
+            message,
+            warnings,
+            nextSteps,
+        };
+    }
+    catch (err) {
+        return {
+            kind: 'failure',
+            success: false,
+            extensionId,
+            warnings,
+            nextSteps,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+}
+/**
+ * Read the version currently pinned for `packageId` in the project manifest, or
+ * `null` when the dependency is absent. Used to classify the outcome as
+ * added / updated / already-up-to-date, which `addPackageToManifest`'s
+ * `{ modified }` flag cannot express on its own.
+ *
+ * Deliberately forgiving: any read/parse problem yields `null` (treated as
+ * "not installed"). The subsequent `addPackageToManifest` call performs the
+ * authoritative read and throws a precise error if the manifest is unusable, so
+ * swallowing here cannot mask a real failure — it only avoids duplicating the
+ * error path.
+ */
+function readInstalledVersion(manifestPath, packageId) {
+    try {
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const current = parsed?.dependencies?.[packageId];
+        return typeof current === 'string' && current.trim() !== '' ? current : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Return a descriptor with the `version` override applied (empty/whitespace override is ignored). */
+function applyVersionOverride(descriptor, version, warnings) {
+    const v = (version ?? '').trim();
+    if (v === '')
+        return descriptor;
+    if (descriptor.version !== null && descriptor.version !== v) {
+        warnings.push(`version ${v} overrides the catalogue pin ${descriptor.packageId}@${descriptor.version} for this install.`);
+    }
+    return { ...descriptor, version: v };
+}
+/** A clear "unknown extension" error that lists what IS installable (or says the catalogue is empty). */
+function unknownExtensionMessage(id, catalog) {
+    if (catalog.length === 0) {
+        return (`Unknown extension "${id}". The Unity-MCP extension catalogue is currently empty, ` +
+            'so there is nothing to install.');
+    }
+    const available = catalog.map((d) => d.packageId).join(', ');
+    return `Unknown extension "${id}". Available extensions: ${available}.`;
+}
+//# sourceMappingURL=install-extension.js.map

package/dist/lib/install-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-extension.js","sourceRoot":"","sources":["../../src/lib/install-extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,UAAU,GAEX,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAA6B;IAE7B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,WAAW,GAAG,IAAI,EAAE,WAAW,IAAI,EAAE,CAAC;IAE5C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,kBAAkB,CAAC;QACnD,MAAM,QAAQ,GAAG,aAAa,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,KAAK;gBACd,WAAW;gBACX,QAAQ;gBACR,SAAS;gBACT,KAAK,EAAE,IAAI,KAAK,CAAC,uBAAuB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;aAChE,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAC9D,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,KAAK;gBACd,WAAW;gBACX,SAAS,EAAE,QAAQ,CAAC,SAAS;gBAC7B,YAAY,EAAE,SAAS,CAAC,YAAY;gBACpC,QAAQ;gBACR,SAAS;gBACT,KAAK,EAAE,SAAS,CAAC,KAAK;aACvB,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QAElC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE;YAC5B,KAAK,EAAE,OAAO;YACd,OAAO,EAAE,wBAAwB,QAAQ,CAAC,SAAS,SAAS,WAAW,EAAE;SAC1E,CAAC,CAAC;QAEH,8EAA8E;QAC9E,8CAA8C;QAC9C,MAAM,UAAU,GAAG,oBAAoB,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC1E,MAAM,iBAAiB,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAE7D,IAAI,OAAe,CAAC;QACpB,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3B,gFAAgF;YAChF,OAAO,GAAG,UAAU,CAAC,OAAiB,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,MAAM,2BAA2B,CACzC,UAAU,CAAC,SAAS,EACpB,YAAY,EACZ,qBAAqB,CACtB,CAAC;YACF,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE;gBAC5B,KAAK,EAAE,uBAAuB;gBAC9B,OAAO,EAAE,mBAAmB,UAAU,CAAC,SAAS,aAAa,OAAO,EAAE;gBACtE,OAAO;aACR,CAAC,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;QAElF,MAAM,MAAM,GAAG,oBAAoB,CACjC,WAAW,EACX,UAAU,CAAC,SAAS,EACpB,OAAO,EACP,iBAAiB,EACjB,YAAY,CACb,CAAC;QAEF,gFAAgF;QAChF,gEAAgE;QAChE,IAAI,MAAM,CAAC,eAAe,KAAK,OAAO,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC7D,QAAQ,CAAC,IAAI,CACX,GAAG,UAAU,CAAC,SAAS,0BAA0B,MAAM,CAAC,eAAe,QAAQ,OAAO,KAAK;gBACzF,gFAAgF,CACnF,CAAC;QACJ,CAAC;QAED,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE;YAC5B,KAAK,EAAE,kBAAkB;YACzB,OAAO,EAAE,MAAM,CAAC,QAAQ;gBACtB,CAAC,CAAC,WAAW,MAAM,CAAC,YAAY,EAAE;gBAClC,CAAC,CAAC,sCAAsC;YAC1C,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;QAEH,+EAA+E;QAC/E,iFAAiF;QACjF,+CAA+C;QAC/C,MAAM,OAAO,GACX,MAAM,KAAK,IAAI;YACb,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,MAAM,CAAC,eAAe,KAAK,MAAM;gBACjC,CAAC,CAAC,oBAAoB;gBACtB,CAAC,CAAC,SAAS,CAAC;QAElB,MAAM,OAAO,GACX,OAAO,KAAK,OAAO;YACjB,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,IAAI,MAAM,CAAC,eAAe,iDAAiD;YAC1G,CAAC,CAAC,OAAO,KAAK,SAAS;gBACrB,CAAC,CAAC,WAAW,UAAU,CAAC,SAAS,SAAS,MAAM,OAAO,MAAM,CAAC,eAAe,GAAG;gBAChF,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,yCAAyC,MAAM,CAAC,eAAe,IAAI,CAAC;QAE9F,IAAI,OAAO,KAAK,oBAAoB,EAAE,CAAC;YACrC,SAAS,CAAC,IAAI,CACZ,sFAAsF,CACvF,CAAC;QACJ,CAAC;QAED,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAC,CAAC;QAEzF,OAAO;YACL,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,IAAI;YACb,OAAO;YACP,OAAO,EAAE,OAAO,KAAK,oBAAoB;YACzC,WAAW;YACX,SAAS,EAAE,UAAU,CAAC,SAAS;YAC/B,WAAW,EAAE,MAAM;YACnB,SAAS,EAAE,MAAM,CAAC,eAAe;YACjC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,OAAO;YACP,QAAQ;YACR,SAAS;SACV,CAAC;IACJ,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,WAAW;YACX,QAAQ;YACR,SAAS;YACT,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC3D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,oBAAoB,CAAC,YAAoB,EAAE,SAAiB;IACnE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA8C,CAAC;QAC5E,MAAM,OAAO,GAAG,MAAM,EAAE,YAAY,EAAE,CAAC,SAAS,CAAC,CAAC;QAClD,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,sGAAsG;AACtG,SAAS,oBAAoB,CAC3B,UAA+B,EAC/B,OAA2B,EAC3B,QAAkB;IAElB,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,UAAU,CAAC;IAChC,IAAI,UAAU,CAAC,OAAO,KAAK,IAAI,IAAI,UAAU,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAC5D,QAAQ,CAAC,IAAI,CACX,WAAW,CAAC,gCAAgC,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,OAAO,oBAAoB,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AACvC,CAAC;AAED,yGAAyG;AACzG,SAAS,uBAAuB,CAC9B,EAAU,EACV,OAAuC;IAEvC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CACL,sBAAsB,EAAE,2DAA2D;YACnF,iCAAiC,CAClC,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,OAAO,sBAAsB,EAAE,4BAA4B,SAAS,GAAG,CAAC;AAC1E,CAAC"}

package/dist/lib/run-tool.js

@@ -5,6 +5,7 @@
 // - Errors are returned in `{ kind: 'failure', success: false, ... }`,
 //   never thrown past the public boundary.
 import { readConfig, resolveConnectionFromConfig, isCloudMode } from '../utils/config.js';
+import { readCloudAccessToken, refreshCloudAccessToken } from '../utils/cloud-credentials.js';
 import { generatePortFromDirectory } from '../utils/port.js';
 import { requireProjectPath } from './validation.js';
 const DEFAULT_TIMEOUT_MS = 60000;
@@ -30,22 +31,10 @@ async function invokeTool(routePrefix, opts) {
     const validationFailure = validateOptions(opts);
     if (validationFailure)
         return validationFailure;
-    const resolved = resolveConnection(opts);
-    if (resolved.kind === 'failure')
-        return resolved;
-    const { url, token } = resolved;
-    const body = serializeInput(opts.input);
-    if ('error' in body) {
-        return makeFailure({
-            endpoint: '',
-            reason: 'invalid-input',
-            message: body.error.message,
-            error: body.error,
-        });
-    }
-    const endpoint = `${url}${routePrefix}/${encodeURIComponent(opts.toolName)}`;
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     const timeoutMs = typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+    // Wire the abort/timeout plumbing BEFORE the first await so an external abort issued right
+    // after the call is never lost (connection resolution below may itself await a token refresh).
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     const externalAbort = () => controller.abort();
@@ -55,35 +44,76 @@ async function invokeTool(routePrefix, opts) {
         else
             opts.signal.addEventListener('abort', externalAbort, { once: true });
     }
-    const headers = { 'Content-Type': 'application/json' };
-    if (token)
-        headers['Authorization'] = `Bearer ${token}`;
+    let endpoint = '';
     try {
-        const response = await fetchImpl(endpoint, {
-            method: 'POST',
-            headers,
-            body: body.json,
-            signal: controller.signal,
-        });
-        const text = await safeReadText(response);
-        const data = parseJsonOrText(text);
-        if (!response.ok) {
+        const resolved = await resolveConnection(opts);
+        if (resolved.kind === 'failure')
+            return resolved;
+        const { url, token } = resolved;
+        const body = serializeInput(opts.input);
+        if ('error' in body) {
             return makeFailure({
+                endpoint: '',
+                reason: 'invalid-input',
+                message: body.error.message,
+                error: body.error,
+            });
+        }
+        endpoint = `${url}${routePrefix}/${encodeURIComponent(opts.toolName)}`;
+        // Reactive-refresh loop (unified-machine-auth 04 §3 rule 1): when the Bearer came from the
+        // shared machine credential store and the server answers 401 — revocation or clock skew the
+        // proactive expiry check could not see — refresh the plugin family once under the
+        // cross-process lock and retry the call with the rotated token. At most ONE reactive attempt
+        // per invocation; an explicit --token / --url override is never refreshed. Both attempts
+        // share one timeout.
+        let bearer = token;
+        let attemptedReactiveRefresh = false;
+        for (;;) {
+            // Mirror fetch's contract for an ALREADY-aborted signal (an external abort may land while
+            // connection resolution above is awaiting): reject up front instead of relying on the
+            // 'abort' event, which has already fired.
+            if (controller.signal.aborted) {
+                throw new DOMException('The operation was aborted', 'AbortError');
+            }
+            const headers = { 'Content-Type': 'application/json' };
+            if (bearer)
+                headers['Authorization'] = `Bearer ${bearer}`;
+            const response = await fetchImpl(endpoint, {
+                method: 'POST',
+                headers,
+                body: body.json,
+                signal: controller.signal,
+            });
+            const text = await safeReadText(response);
+            const data = parseJsonOrText(text);
+            if (!response.ok) {
+                if (response.status === 401 &&
+                    resolved.tokenFromCloudStore &&
+                    !attemptedReactiveRefresh) {
+                    attemptedReactiveRefresh = true;
+                    const fresh = await (opts.refreshCloudToken ?? refreshCloudAccessToken)();
+                    if (fresh) {
+                        bearer = fresh;
+                        continue;
+                    }
+                }
+                return makeFailure({
+                    endpoint,
+                    reason: 'http-error',
+                    httpStatus: response.status,
+                    data,
+                    message: response.statusText || `HTTP ${response.status}`,
+                });
+            }
+            const success = {
+                kind: 'success',
+                success: true,
                 endpoint,
-                reason: 'http-error',
                 httpStatus: response.status,
                 data,
-                message: response.statusText || `HTTP ${response.status}`,
-            });
+            };
+            return success;
         }
-        const success = {
-            kind: 'success',
-            success: true,
-            endpoint,
-            httpStatus: response.status,
-            data,
-        };
-        return success;
     }
     catch (err) {
         return classifyFetchError(err, endpoint, timeoutMs);
@@ -119,9 +149,14 @@ function validateOptions(opts) {
     }
     return null;
 }
-function resolveConnection(opts) {
+async function resolveConnection(opts) {
     if (opts.url) {
-        return { kind: 'success', url: opts.url.replace(/\/$/, ''), token: opts.token };
+        return {
+            kind: 'success',
+            url: opts.url.replace(/\/$/, ''),
+            token: opts.token,
+            tokenFromCloudStore: false,
+        };
     }
     // `unityProjectPath` is library-only — does NOT require an `Assets/`
     // folder, unlike the CLI's `resolveAndValidateProjectPath`. The
@@ -138,7 +173,9 @@ function resolveConnection(opts) {
     const projectPath = validated.projectPath;
     const config = readConfig(projectPath);
     const fromConfig = config
-        ? resolveConnectionFromConfig(config, { readCloudToken: opts.readCloudToken })
+        ? await resolveConnectionFromConfig(config, {
+            readCloudToken: opts.readCloudToken ?? readCloudAccessToken,
+        })
         : { url: undefined, token: undefined };
     const url = fromConfig.url
         ? fromConfig.url.replace(/\/$/, '')
@@ -154,7 +191,8 @@ function resolveConnection(opts) {
             message: 'Not logged in to ai-game.dev. Run `unity-mcp-cli login` to sign in, or pass an explicit --token / --url.',
         });
     }
-    return { kind: 'success', url, token };
+    const tokenFromCloudStore = !!config && isCloudMode(config) && !opts.token && !!token;
+    return { kind: 'success', url, token, tokenFromCloudStore };
 }
 function serializeInput(input) {
     if (input === undefined || input === null)

package/dist/lib/run-tool.js.map

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

package/dist/lib/types.d.ts

@@ -1,3 +1,4 @@
+import type { ExtensionDescriptor } from '../utils/extensions-catalog.js';
 /**
  * Discriminated union describing every progress event the library can
  * emit to the optional `onProgress` callback.
@@ -120,6 +121,84 @@ export interface InstallFailure {
     error: Error;
 }
 export type InstallResult = InstallSuccess | InstallFailure;
+/**
+ * What `installExtension` actually did. Distinguished from `changed` because a
+ * caller usually wants to say "installed" vs "updated" vs "nothing to do" in its
+ * UI, and `changed` alone cannot tell the first two apart.
+ */
+export type InstallExtensionOutcome = 'added' | 'updated' | 'already-up-to-date';
+export interface InstallExtensionOptions {
+    /** Absolute or relative path to the Unity project's root. */
+    unityProjectPath: string;
+    /**
+     * Extension to install — either the OpenUPM package id
+     * (`com.ivanmurzak.unity.mcp.tilemap`) or the catalogue display name
+     * (`Tilemap`). Matched case-insensitively, package id first.
+     */
+    extensionId: string;
+    /**
+     * Version to install. When omitted, OpenUPM's `dist-tags.latest` is resolved
+     * live at install time — which is the normal path, because every catalogue
+     * entry is unpinned (`version: null`). Supplying a value also permits a
+     * downgrade, mirroring `installPlugin`'s explicit-version semantics.
+     */
+    version?: string;
+    /**
+     * Catalogue override, for tests and for callers that carry their own list.
+     * Defaults to the built-in `EXTENSIONS_CATALOG`.
+     */
+    catalog?: readonly ExtensionDescriptor[];
+    /**
+     * Optional progress callback — fires for `start`, `dependencies-resolved`
+     * (when the version was auto-resolved), `manifest-patched`, and `done`.
+     */
+    onProgress?: ProgressCallback;
+}
+/** Successful `installExtension` outcome. Narrow with `kind === 'success'`. */
+export interface InstallExtensionSuccess {
+    kind: 'success';
+    /** Always `true` for the success variant. */
+    success: true;
+    /** What happened — see {@link InstallExtensionOutcome}. */
+    outcome: InstallExtensionOutcome;
+    /** `true` when `manifest.json` was written. `false` for `already-up-to-date`. */
+    changed: boolean;
+    /** The `extensionId` as supplied by the caller. */
+    extensionId: string;
+    /** The resolved OpenUPM package id that was written to the manifest. */
+    packageId: string;
+    /** Version present before the call, or `null` when the extension was absent. */
+    fromVersion: string | null;
+    /** Version present after the call. */
+    toVersion: string;
+    /** Absolute path to the `Packages/manifest.json` that was inspected / written. */
+    manifestPath: string;
+    /** Human-readable summary the caller may surface directly. */
+    message: string;
+    /** Non-fatal warnings collected during the run. */
+    warnings: string[];
+    /** Suggested next steps for the caller to surface to a human user. */
+    nextSteps: string[];
+}
+/** Failed `installExtension` outcome. Narrow with `kind === 'failure'`. */
+export interface InstallExtensionFailure {
+    kind: 'failure';
+    /** Always `false` for the failure variant. */
+    success: false;
+    /** The `extensionId` as supplied by the caller. */
+    extensionId: string;
+    /** Resolved package id, when catalogue lookup succeeded before the failure. */
+    packageId?: string;
+    /** Manifest path may be known even on failure (e.g. a validation failure that reached it). */
+    manifestPath?: string;
+    /** Non-fatal warnings collected before the failure. */
+    warnings: string[];
+    /** Suggested next steps the caller may surface to a human user. */
+    nextSteps: string[];
+    /** The captured error. Never thrown past this boundary. */
+    error: Error;
+}
+export type InstallExtensionResult = InstallExtensionSuccess | InstallExtensionFailure;
 export interface RemovePluginOptions {
     unityProjectPath: string;
     onProgress?: ProgressCallback;
@@ -558,11 +637,20 @@ export interface RunToolOptions {
     fetchImpl?: typeof fetch;
     /**
      * Optional injection point for the Cloud-mode Bearer credential read from the shared machine
-     * credential store (`~/.ai-game-dev/credentials.json`). Only consulted when the resolved project
-     * config is in Cloud mode and neither `url` nor `token` was supplied. Defaults to reading the real
-     * per-machine store; tests inject a deterministic value.
+     * credential store. Only consulted when the resolved project config is in Cloud mode and neither
+     * `url` nor `token` was supplied. Defaults to cli-core's `MachineCredentialProvider` (proactive
+     * refresh under the cross-process lock — never a raw on-disk read); tests inject a deterministic
+     * value. Sync or async both work.
+     */
+    readCloudToken?: () => Promise<string | undefined> | string | undefined;
+    /**
+     * Optional injection point for the REACTIVE Cloud-mode refresh: invoked at most once per call
+     * when the server answers 401 to a machine-store Bearer (revocation / clock skew). Returns the
+     * rotated access token, or `undefined` when the credential family is dead (the call then fails
+     * with the original 401). Defaults to cli-core's `MachineCredentialProvider.refresh`. Never
+     * consulted for an explicit `token` / `url` override.
      */
-    readCloudToken?: () => string | undefined;
+    refreshCloudToken?: () => Promise<string | undefined> | string | undefined;
 }
 /** Successful `runTool` / `runSystemTool` outcome. Narrow with `kind === 'success'`. */
 export interface RunToolSuccess {

package/dist/lib.d.ts

@@ -1,8 +1,11 @@
 export { installPlugin } from './lib/install-plugin.js';
+export { installExtension } from './lib/install-extension.js';
 export { removePlugin } from './lib/remove-plugin.js';
 export { configure } from './lib/configure.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
 export { openProject } from './lib/open.js';
 export { createProject } from './lib/create-project.js';
 export { runTool, runSystemTool } from './lib/run-tool.js';
-export type { ProgressEvent, ProgressCallback, ResultKind, InstallPluginOptions, InstallResult, InstallSuccess, InstallFailure, RemovePluginOptions, RemoveResult, RemoveSuccess, RemoveFailure, ConfigureOptions, ConfigureResult, ConfigureSuccess, ConfigureFailure, ConfigureSnapshot, FeatureAction, McpFeatureSnapshot, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, McpTransport, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectTransport, CreateProjectOptions, CreateProjectResult, CreateProjectSuccess, CreateProjectFailure, CreateProjectEditorInfo, RunToolOptions, RunToolResult, RunToolSuccess, RunToolFailure, RunToolFailureReason, RunSystemToolOptions, RunSystemToolResult, RunSystemToolSuccess, RunSystemToolFailure, } from './lib/types.js';
+export { EXTENSIONS_CATALOG, findExtension, hasVersion, } from './utils/extensions-catalog.js';
+export type { ExtensionDescriptor, ExtensionTool, } from './utils/extensions-catalog.js';
+export type { ProgressEvent, ProgressCallback, ResultKind, InstallPluginOptions, InstallResult, InstallSuccess, InstallFailure, InstallExtensionOptions, InstallExtensionResult, InstallExtensionSuccess, InstallExtensionFailure, InstallExtensionOutcome, RemovePluginOptions, RemoveResult, RemoveSuccess, RemoveFailure, ConfigureOptions, ConfigureResult, ConfigureSuccess, ConfigureFailure, ConfigureSnapshot, FeatureAction, McpFeatureSnapshot, SetupMcpOptions, SetupMcpResult, SetupMcpSuccess, SetupMcpFailure, McpTransport, OpenProjectOptions, OpenProjectResult, OpenProjectSuccess, OpenProjectFailure, OpenProjectAuthOption, OpenProjectTransport, CreateProjectOptions, CreateProjectResult, CreateProjectSuccess, CreateProjectFailure, CreateProjectEditorInfo, RunToolOptions, RunToolResult, RunToolSuccess, RunToolFailure, RunToolFailureReason, RunSystemToolOptions, RunSystemToolResult, RunSystemToolSuccess, RunSystemToolFailure, } from './lib/types.js';

package/dist/lib.js

@@ -16,10 +16,15 @@
 // Consumers: `import { installPlugin } from 'unity-mcp-cli'` (maps to
 // this file via the `exports` field in package.json).
 export { installPlugin } from './lib/install-plugin.js';
+export { installExtension } from './lib/install-extension.js';
 export { removePlugin } from './lib/remove-plugin.js';
 export { configure } from './lib/configure.js';
 export { setupMcp, listAgentIds } from './lib/setup-mcp.js';
 export { openProject } from './lib/open.js';
 export { createProject } from './lib/create-project.js';
 export { runTool, runSystemTool } from './lib/run-tool.js';
+// The extension catalogue is part of the public library surface: a consumer that
+// renders an "install an extension" list (the desktop app) needs the same ten
+// entries the CLI installs from, and must not re-declare them.
+export { EXTENSIONS_CATALOG, findExtension, hasVersion, } from './utils/extensions-catalog.js';
 //# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -1 +1 @@
-{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,qDAAqD;AACrD,iEAAiE;AACjE,sEAAsE;AACtE,oDAAoD;AACpD,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,iEAAiE;AACjE,oEAAoE;AACpE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,qDAAqD;AACrD,iEAAiE;AACjE,sEAAsE;AACtE,oDAAoD;AACpD,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,iEAAiE;AACjE,oEAAoE;AACpE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE3D,iFAAiF;AACjF,8EAA8E;AAC9E,+DAA+D;AAC/D,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,UAAU,GACX,MAAM,+BAA+B,CAAC"}

package/dist/utils/cloud-credentials.d.ts

@@ -0,0 +1,43 @@
+import { MachineCredentialProvider, MachineCredentialStore } from '@baizor/gamedev-cli-core';
+/**
+ * The CLI's single seam onto cli-core's `MachineCredentialProvider` (unified-machine-auth 02/04,
+ * task d2 / W2). Every Cloud-mode Bearer the CLI presents comes through here — the provider owns
+ * proactive refresh (inside the 60 s expiry skew), reactive refresh (driven by a hub 401), the
+ * cross-process credential lock, and the family-aware machine-store view. The CLI never reads
+ * `accessToken` raw off disk: a raw read returns a token that may be seconds from expiry (or past
+ * it) with nobody refreshing, which is exactly the defect this module replaces
+ * (the pre-d2 `readMachineStoreCloudToken`).
+ */
+/** Injectable construction options — tests point the provider at a temp store + a fake AS. */
+export interface CloudCredentialProviderOptions {
+    /** The credential store to serve from; defaults to the shared per-machine store. */
+    store?: MachineCredentialStore;
+    /** Authorization-server base for the refresh endpoint; defaults to the hosted cloud. */
+    serverBaseUrl?: string;
+    /** Injectable `fetch` for the refresher (tests). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build a `MachineCredentialProvider` wired the way this CLI consumes it:
+ * `HttpTokenRefresher` against the AS root, and `unity-mcp-cli` as the component-default client
+ * id — used ONLY for `families.legacy` (a stored family's own `clientId` always wins, 04 §3).
+ */
+export declare function createCloudCredentialProvider(options?: CloudCredentialProviderOptions): MachineCredentialProvider;
+/** TEST-ONLY: drop the cached default provider (e.g. after re-pointing HOME). */
+export declare function resetCloudCredentialProviderForTests(): void;
+/**
+ * Read a valid plugin-plane access token for a Cloud-mode call, PROACTIVELY refreshing under the
+ * cross-process lock when the stored token is within the expiry skew. Returns `undefined` when the
+ * machine is effectively not signed in — no credential, a dead family, an unreadable store, or a
+ * lock that stayed contended — so callers surface their actionable "not logged in" error instead
+ * of issuing a silent unauthenticated request (defect E / D11). The precise reason is logged via
+ * `verbose()` (never token bytes).
+ */
+export declare function readCloudAccessToken(options?: CloudCredentialProviderOptions): Promise<string | undefined>;
+/**
+ * REACTIVELY refresh the plugin-plane family now — the hub answered 401 while the local expiry
+ * still looked fine (revocation, clock skew). Runs the same locked critical section as the
+ * proactive path. Returns the fresh access token, or `undefined` when the family is dead /
+ * signed out (the caller falls back to its "not logged in" error).
+ */
+export declare function refreshCloudAccessToken(options?: CloudCredentialProviderOptions): Promise<string | undefined>;