uloop-cli 0.55.2 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.55.2",
+  "version": "0.57.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -41,23 +41,24 @@
     "provenance": true
   },
   "dependencies": {
-    "commander": "^14.0.2",
-    "semver": "^7.7.3"
+    "commander": "14.0.2",
+    "launch-unity": "0.12.0",
+    "semver": "7.7.3"
   },
   "devDependencies": {
     "@eslint/js": "9.39.2",
-    "tsx": "4.21.0",
     "@types/jest": "30.0.0",
     "@types/node": "25.0.2",
-    "@types/semver": "^7.7.1",
+    "@types/semver": "7.7.1",
     "esbuild": "0.27.1",
     "eslint": "9.39.2",
-    "eslint-config-prettier": "^10.1.8",
+    "eslint-config-prettier": "10.1.8",
     "eslint-plugin-prettier": "5.5.4",
     "eslint-plugin-security": "3.0.1",
     "jest": "30.2.0",
     "prettier": "3.7.4",
     "ts-jest": "29.4.6",
+    "tsx": "4.21.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.49.0"
   }

package/src/__tests__/cli-e2e.test.ts

@@ -482,6 +482,46 @@ describe('CLI E2E Tests (requires running Unity)', () => {
     });
   });
 
+  describe('launch', () => {
+    it('should display launch command help', () => {
+      const { stdout, exitCode } = runCli('launch --help');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Launch Unity project');
+      expect(stdout).toContain('--restart');
+      expect(stdout).toContain('--platform');
+      expect(stdout).toContain('--max-depth');
+      expect(stdout).toContain('--add-unity-hub');
+      expect(stdout).toContain('--favorite');
+    });
+
+    it('should detect already running Unity and focus window', () => {
+      // Unity is already running for this test suite, so launch should detect it
+      const { stdout, exitCode } = runCli(`launch "${UNITY_PROJECT_ROOT}"`);
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Unity process already running');
+    });
+
+    it('should fail gracefully when project not found', () => {
+      const { stdout, stderr, exitCode } = runCli('launch /nonexistent/path/to/project');
+
+      expect(exitCode).not.toBe(0);
+      // Error message should mention project not found or version file not found
+      const output = stderr || stdout;
+      expect(output).toMatch(/not found|does not appear to be a Unity project/i);
+    });
+
+    it('should search for Unity project from current directory', () => {
+      // This test runs from Unity project root, so it should find the project
+      const { stdout, exitCode } = runCli('launch');
+
+      expect(exitCode).toBe(0);
+      // Should either find and focus existing Unity or report no Unity found
+      expect(stdout).toMatch(/Unity process already running|Selected project/);
+    });
+  });
+
   // Domain Reload tests must run last to avoid affecting other tests
   describe('compile --force-recompile (Domain Reload)', () => {
     it('should support --force-recompile option', () => {

package/src/cli.ts

@@ -18,10 +18,18 @@ 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 { registerLaunchCommand } from './commands/launch.js';
 import { VERSION } from './version.js';
 import { findUnityProjectRoot } from './project-root.js';
 
@@ -29,7 +37,15 @@ interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
 }
 
-const BUILTIN_COMMANDS = ['list', 'sync', 'completion', 'update', 'fix', 'skills'] as const;
+const BUILTIN_COMMANDS = [
+  'list',
+  'sync',
+  'completion',
+  'update',
+  'fix',
+  'skills',
+  'launch',
+] as const;
 
 const program = new Command();
 
@@ -87,6 +103,9 @@ program
 // Register skills subcommand
 registerSkillsCommand(program);
 
+// Register launch subcommand
+registerLaunchCommand(program);
+
 /**
  * Register a tool as a CLI command dynamically.
  */
@@ -274,12 +293,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 +350,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/commands/launch.ts

@@ -0,0 +1,125 @@
+/**
+ * CLI command for launching Unity projects.
+ * Integrates launch-unity library into uloop CLI.
+ */
+
+// CLI commands output to console by design
+/* eslint-disable no-console */
+
+import { Command } from 'commander';
+import { resolve } from 'path';
+
+import {
+  findUnityProjectBfs,
+  getUnityVersion,
+  launch,
+  findRunningUnityProcess,
+  focusUnityProcess,
+  killRunningUnity,
+  handleStaleLockfile,
+  ensureProjectEntryAndUpdate,
+  updateLastModifiedIfExists,
+  LaunchResolvedOptions,
+} from 'launch-unity';
+
+interface LaunchCommandOptions {
+  restart?: boolean;
+  platform?: string;
+  maxDepth?: string;
+  addUnityHub?: boolean;
+  favorite?: boolean;
+}
+
+export function registerLaunchCommand(program: Command): void {
+  program
+    .command('launch')
+    .description('Launch Unity project with matching Editor version')
+    .argument('[project-path]', 'Path to Unity project')
+    .option('-r, --restart', 'Kill running Unity and restart')
+    .option('-p, --platform <platform>', 'Build target (e.g., Android, iOS)')
+    .option('--max-depth <n>', 'Search depth when project-path is omitted', '3')
+    .option('-a, --add-unity-hub', 'Add to Unity Hub (does not launch)')
+    .option('-f, --favorite', 'Add to Unity Hub as favorite (does not launch)')
+    .action(async (projectPath: string | undefined, options: LaunchCommandOptions) => {
+      await runLaunchCommand(projectPath, options);
+    });
+}
+
+function parseMaxDepth(value: string | undefined): number {
+  if (value === undefined) {
+    return 3;
+  }
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    console.error(`Error: Invalid --max-depth value: "${value}". Must be an integer.`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+async function runLaunchCommand(
+  projectPath: string | undefined,
+  options: LaunchCommandOptions,
+): Promise<void> {
+  const maxDepth = parseMaxDepth(options.maxDepth);
+
+  let resolvedProjectPath: string | undefined = projectPath ? resolve(projectPath) : undefined;
+
+  if (!resolvedProjectPath) {
+    const searchRoot = process.cwd();
+    const depthInfo = maxDepth === -1 ? 'unlimited' : String(maxDepth);
+    console.log(
+      `No project-path provided. Searching under ${searchRoot} (max-depth: ${depthInfo})...`,
+    );
+    const found = findUnityProjectBfs(searchRoot, maxDepth);
+    if (!found) {
+      console.error(`Error: Unity project not found under ${searchRoot}.`);
+      process.exit(1);
+    }
+    console.log(`Selected project: ${found}`);
+    resolvedProjectPath = found;
+  }
+
+  const unityVersion = getUnityVersion(resolvedProjectPath);
+
+  const unityHubOnlyMode = options.addUnityHub === true || options.favorite === true;
+  if (unityHubOnlyMode) {
+    console.log(`Detected Unity version: ${unityVersion}`);
+    console.log(`Project Path: ${resolvedProjectPath}`);
+    const now = new Date();
+    await ensureProjectEntryAndUpdate(
+      resolvedProjectPath,
+      unityVersion,
+      now,
+      options.favorite === true,
+    );
+    console.log('Unity Hub entry updated.');
+    return;
+  }
+
+  if (options.restart === true) {
+    await killRunningUnity(resolvedProjectPath);
+  } else {
+    const runningProcess = await findRunningUnityProcess(resolvedProjectPath);
+    if (runningProcess) {
+      console.log(
+        `Unity process already running for project: ${resolvedProjectPath} (PID: ${runningProcess.pid})`,
+      );
+      await focusUnityProcess(runningProcess.pid);
+      return;
+    }
+  }
+
+  await handleStaleLockfile(resolvedProjectPath);
+
+  const resolved: LaunchResolvedOptions = {
+    projectPath: resolvedProjectPath,
+    platform: options.platform,
+    unityArgs: [],
+    unityVersion,
+  };
+  launch(resolved);
+
+  const now = new Date();
+  await updateLastModifiedIfExists(resolvedProjectPath, now);
+}

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.55.2",
+  "version": "0.57.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/skills/skill-definitions/cli-only/uloop-launch/Skill/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: uloop-launch
+description: "Launch Unity project with matching Editor version via uloop CLI. Use when you need to: (1) Open a Unity project with the correct Editor version, (2) Restart Unity to apply changes, (3) Switch build target when launching."
+---
+
+# uloop launch
+
+Launch Unity Editor with the correct version for a project.
+
+## Usage
+
+```bash
+uloop launch [project-path] [options]
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `project-path` | string | Path to Unity project (optional, searches current directory if omitted) |
+| `-r, --restart` | boolean | Kill running Unity and restart |
+| `-p, --platform <P>` | string | Build target (e.g., StandaloneOSX, Android, iOS) |
+| `--max-depth <N>` | number | Search depth when project-path is omitted (default: 3, -1 for unlimited) |
+| `-a, --add-unity-hub` | boolean | Add to Unity Hub only (does not launch) |
+| `-f, --favorite` | boolean | Add to Unity Hub as favorite (does not launch) |
+
+## Examples
+
+```bash
+# Search for Unity project in current directory and launch
+uloop launch
+
+# Launch specific project
+uloop launch /path/to/project
+
+# Restart Unity (kill existing and relaunch)
+uloop launch -r
+
+# Launch with build target
+uloop launch -p Android
+
+# Add project to Unity Hub without launching
+uloop launch -a
+```
+
+## Output
+
+- Prints detected Unity version
+- Prints project path
+- If Unity is already running, focuses the existing window
+- If launching, opens Unity in background

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.57.0'; // x-release-please-version