uloop-cli 0.55.2 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.55.2",
+  "version": "0.56.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",

package/src/cli.ts

@@ -18,8 +18,15 @@ import {
   listAvailableTools,
   GlobalOptions,
   syncTools,
+  isVersionOlder,
 } from './execute-tool.js';
-import { loadToolsCache, hasCacheFile, ToolDefinition, ToolProperty } from './tool-cache.js';
+import {
+  loadToolsCache,
+  hasCacheFile,
+  ToolDefinition,
+  ToolProperty,
+  getCachedServerVersion,
+} from './tool-cache.js';
 import { pascalToKebabCase } from './arg-parser.js';
 import { registerSkillsCommand } from './skills/skills-command.js';
 import { VERSION } from './version.js';
@@ -274,12 +281,45 @@ function printConnectionError(): void {
   console.error('[For AI] Please report the above to the user.');
 }
 
+/**
+ * Print version mismatch diagnostic information when errors occur.
+ * Only prints if versions are mismatched.
+ */
+function printVersionMismatchDiagnostic(): void {
+  const serverVersion = getCachedServerVersion();
+  if (serverVersion === undefined) {
+    return;
+  }
+
+  if (serverVersion === VERSION) {
+    return;
+  }
+
+  const isCliOlder = isVersionOlder(VERSION, serverVersion);
+  const action = isCliOlder ? 'Update' : 'Downgrade';
+  const updateCommand = `npm install -g uloop-cli@${serverVersion}`;
+
+  console.error('');
+  console.error('\x1b[33m━━━ Version Mismatch Diagnostic ━━━\x1b[0m');
+  console.error('');
+  console.error(`  CLI version:     ${VERSION}`);
+  console.error(`  Unity package:   ${serverVersion}`);
+  console.error('  Version mismatch may cause communication errors.');
+  console.error('');
+  console.error(`  To fix: ${action} CLI to match Unity package version`);
+  console.error(`    ${updateCommand}`);
+  console.error('');
+  console.error('[For AI] Please ask the user if they would like to run this command.');
+  console.error('\x1b[33m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\x1b[0m');
+}
+
 async function runWithErrorHandling(fn: () => Promise<void>): Promise<void> {
   try {
     await fn();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
 
+    // Unity busy states have clear causes - no version diagnostic needed
     if (message === 'UNITY_COMPILING') {
       console.error('\x1b[33m⏳ Unity is compiling scripts.\x1b[0m');
       console.error('Please wait for compilation to finish and try again.');
@@ -298,14 +338,24 @@ async function runWithErrorHandling(fn: () => Promise<void>): Promise<void> {
       process.exit(1);
     }
 
+    // Errors that may be caused by version mismatch - show diagnostic
     if (message === 'UNITY_NO_RESPONSE') {
       console.error('\x1b[33m⏳ Unity is busy (no response received).\x1b[0m');
       console.error('Unity may be compiling, reloading, or starting. Please wait and try again.');
+      printVersionMismatchDiagnostic();
       process.exit(1);
     }
 
     if (isConnectionError(message)) {
       printConnectionError();
+      printVersionMismatchDiagnostic();
+      process.exit(1);
+    }
+
+    // Timeout errors
+    if (message.includes('Request timed out')) {
+      console.error(`\x1b[31mError: ${message}\x1b[0m`);
+      printVersionMismatchDiagnostic();
       process.exit(1);
     }
 

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.55.2",
+  "version": "0.56.0",
   "tools": [
     {
       "name": "compile",
@@ -142,6 +142,11 @@
           "IncludePaths": {
             "type": "boolean",
             "description": "Include path information"
+          },
+          "UseSelection": {
+            "type": "boolean",
+            "description": "Use selected GameObject(s) as root(s). When true, RootPath is ignored.",
+            "default": false
           }
         }
       }

package/src/direct-unity-client.ts

@@ -75,7 +75,7 @@ export class DirectUnityClient {
       const timeoutId = setTimeout(() => {
         reject(
           new Error(
-            `Request timed out after ${NETWORK_TIMEOUT_MS}ms. Unity may be frozen or busy. Please report this to the user and ask how to proceed. Do NOT kill Unity processes without user permission.`,
+            `Request timed out after ${NETWORK_TIMEOUT_MS}ms. Unity may be frozen or busy. [For AI] Please report this to the user and ask how to proceed. Do NOT kill Unity processes without user permission.`,
           ),
         );
       }, NETWORK_TIMEOUT_MS);

package/src/execute-tool.ts

@@ -80,7 +80,7 @@ function isRetryableError(error: unknown): boolean {
  * Returns true if v1 < v2, false otherwise.
  * Falls back to string comparison if versions are invalid.
  */
-function isVersionOlder(v1: string, v2: string): boolean {
+export function isVersionOlder(v1: string, v2: string): boolean {
   const parsed1 = semver.valid(v1);
   const parsed2 = semver.valid(v2);
 
@@ -321,6 +321,7 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
       spinner.update('Syncing tools...');
       const result = await client.sendRequest<{
         Tools: UnityToolInfo[];
+        Ver?: string;
       }>('get-tool-details', { IncludeDevelopmentOnly: false });
 
       spinner.stop();
@@ -331,6 +332,7 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
 
       const cache: ToolsCache = {
         version: VERSION,
+        serverVersion: result.Ver,
         updatedAt: new Date().toISOString(),
         tools: result.Tools.map((tool) => ({
           name: tool.name,

package/src/tool-cache.ts

@@ -33,6 +33,7 @@ export interface ToolDefinition {
 
 export interface ToolsCache {
   version: string;
+  serverVersion?: string;
   updatedAt?: string;
   tools: ToolDefinition[];
 }
@@ -105,3 +106,23 @@ export function hasCacheFile(): boolean {
 export function getCacheFilePath(): string {
   return getCachePath();
 }
+
+/**
+ * Get the Unity server version from cache file.
+ * Returns undefined if cache doesn't exist, is corrupted, or serverVersion is missing.
+ */
+export function getCachedServerVersion(): string | undefined {
+  const cachePath = getCachePath();
+
+  if (!existsSync(cachePath)) {
+    return undefined;
+  }
+
+  try {
+    const content = readFileSync(cachePath, 'utf-8');
+    const cache = JSON.parse(content) as Partial<ToolsCache>;
+    return typeof cache.serverVersion === 'string' ? cache.serverVersion : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/version.ts

@@ -4,4 +4,4 @@
  * This file exists to avoid bundling the entire package.json into the CLI bundle.
  * This version is automatically updated by release-please.
  */
-export const VERSION = '0.55.2'; // x-release-please-version
+export const VERSION = '0.56.0'; // x-release-please-version