uloop-cli 0.64.1 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.64.1",
+  "version": "0.66.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -42,24 +42,24 @@
   },
   "dependencies": {
     "commander": "14.0.3",
-    "launch-unity": "0.15.1",
+    "launch-unity": "0.16.0",
     "semver": "7.7.4"
   },
   "devDependencies": {
     "@eslint/js": "9.39.2",
     "@types/jest": "30.0.0",
-    "@types/node": "25.2.3",
+    "@types/node": "25.3.0",
     "@types/semver": "7.7.1",
     "esbuild": "0.27.3",
     "eslint": "9.39.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-prettier": "5.5.5",
-    "eslint-plugin-security": "3.0.1",
+    "eslint-plugin-security": "4.0.0",
     "jest": "30.2.0",
     "prettier": "3.8.1",
     "ts-jest": "29.4.6",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.55.0"
+    "typescript-eslint": "8.56.0"
   }
 }

package/src/__tests__/execute-tool.test.ts

@@ -0,0 +1,31 @@
+import { isTransportDisconnectError } from '../execute-tool.js';
+
+describe('isTransportDisconnectError', () => {
+  it('returns true for UNITY_NO_RESPONSE', () => {
+    expect(isTransportDisconnectError(new Error('UNITY_NO_RESPONSE'))).toBe(true);
+  });
+
+  it('returns true for Connection lost with details', () => {
+    expect(isTransportDisconnectError(new Error('Connection lost: read ECONNRESET'))).toBe(true);
+  });
+
+  it('returns true for Connection lost with EPIPE', () => {
+    expect(isTransportDisconnectError(new Error('Connection lost: write EPIPE'))).toBe(true);
+  });
+
+  it('returns false for JSON-RPC error from Unity', () => {
+    expect(isTransportDisconnectError(new Error('Unity error: compilation failed'))).toBe(false);
+  });
+
+  it('returns false for connection refused (pre-dispatch error)', () => {
+    expect(isTransportDisconnectError(new Error('connect ECONNREFUSED 127.0.0.1:8711'))).toBe(
+      false,
+    );
+  });
+
+  it('returns false for non-Error values', () => {
+    expect(isTransportDisconnectError('UNITY_NO_RESPONSE')).toBe(false);
+    expect(isTransportDisconnectError(null)).toBe(false);
+    expect(isTransportDisconnectError(undefined)).toBe(false);
+  });
+});

package/src/__tests__/port-resolver.test.ts

@@ -1,4 +1,9 @@
-import { resolvePortFromUnitySettings } from '../port-resolver.js';
+import { tmpdir } from 'os';
+import {
+  resolvePortFromUnitySettings,
+  validateProjectPath,
+  resolveUnityPort,
+} from '../port-resolver.js';
 
 describe('resolvePortFromUnitySettings', () => {
   it('returns serverPort when server is running and serverPort is valid', () => {
@@ -61,3 +66,28 @@ describe('resolvePortFromUnitySettings', () => {
     expect(port).toBeNull();
   });
 });
+
+describe('validateProjectPath', () => {
+  it('throws when path does not exist', () => {
+    expect(() => validateProjectPath('/nonexistent/path/to/project')).toThrow(
+      'Path does not exist: /nonexistent/path/to/project',
+    );
+  });
+
+  it('throws when path is not a Unity project', () => {
+    expect(() => validateProjectPath(tmpdir())).toThrow('Not a Unity project');
+  });
+});
+
+describe('resolveUnityPort', () => {
+  it('throws when both port and projectPath are specified', async () => {
+    await expect(resolveUnityPort(8700, '/some/path')).rejects.toThrow(
+      'Cannot specify both --port and --project-path',
+    );
+  });
+
+  it('returns explicit port when only port is specified', async () => {
+    const port = await resolveUnityPort(8711);
+    expect(port).toBe(8711);
+  });
+});

package/src/cli.ts

@@ -33,6 +33,7 @@ import { registerLaunchCommand } from './commands/launch.js';
 import { registerFocusWindowCommand } from './commands/focus-window.js';
 import { VERSION } from './version.js';
 import { findUnityProjectRoot } from './project-root.js';
+import { validateProjectPath } from './port-resolver.js';
 
 interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
@@ -73,16 +74,18 @@ program
   .command('list')
   .description('List all available tools from Unity')
   .option('-p, --port <port>', 'Unity TCP port')
+  .option('--project-path <path>', 'Unity project path')
   .action(async (options: CliOptions) => {
-    await runWithErrorHandling(() => listAvailableTools(options));
+    await runWithErrorHandling(() => listAvailableTools(extractGlobalOptions(options)));
   });
 
 program
   .command('sync')
   .description('Sync tool definitions from Unity to local cache')
   .option('-p, --port <port>', 'Unity TCP port')
+  .option('--project-path <path>', 'Unity project path')
   .action(async (options: CliOptions) => {
-    await runWithErrorHandling(() => syncTools(options));
+    await runWithErrorHandling(() => syncTools(extractGlobalOptions(options)));
   });
 
 program
@@ -104,8 +107,12 @@ program
 program
   .command('fix')
   .description('Clean up stale lock files that may prevent CLI from connecting')
-  .action(() => {
-    cleanupLockFiles();
+  .option('--project-path <path>', 'Unity project path')
+  .action(async (options: { projectPath?: string }) => {
+    await runWithErrorHandling(() => {
+      cleanupLockFiles(options.projectPath);
+      return Promise.resolve();
+    });
   });
 
 // Register skills subcommand
@@ -144,6 +151,7 @@ function registerToolCommand(tool: ToolDefinition): void {
 
   // Add global options
   cmd.option('-p, --port <port>', 'Unity TCP port');
+  cmd.option('--project-path <path>', 'Unity project path');
 
   cmd.action(async (options: CliOptions) => {
     const params = buildParams(options, properties);
@@ -294,6 +302,7 @@ function convertValue(value: unknown, propInfo: ToolProperty): unknown {
 function extractGlobalOptions(options: Record<string, unknown>): GlobalOptions {
   return {
     port: options['port'] as string | undefined,
+    projectPath: options['projectPath'] as string | undefined,
   };
 }
 
@@ -592,8 +601,9 @@ const LOCK_FILES = ['compiling.lock', 'domainreload.lock', 'serverstarting.lock'
 /**
  * Clean up stale lock files that may prevent CLI from connecting to Unity.
  */
-function cleanupLockFiles(): void {
-  const projectRoot = findUnityProjectRoot();
+function cleanupLockFiles(projectPath?: string): void {
+  const projectRoot =
+    projectPath !== undefined ? validateProjectPath(projectPath) : findUnityProjectRoot();
   if (projectRoot === null) {
     console.error('Could not find Unity project root.');
     process.exit(1);
@@ -756,6 +766,41 @@ function shouldSkipAutoSync(cmdName: string | undefined, args: string[]): boolea
   return args.some((arg) => (NO_SYNC_FLAGS as readonly string[]).includes(arg));
 }
 
+function extractSyncGlobalOptions(args: string[]): GlobalOptions {
+  const options: GlobalOptions = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--port' || arg === '-p') {
+      const nextArg = args[i + 1];
+      if (nextArg !== undefined && !nextArg.startsWith('-')) {
+        options.port = nextArg;
+      }
+      continue;
+    }
+
+    if (arg.startsWith('--port=')) {
+      options.port = arg.slice('--port='.length);
+      continue;
+    }
+
+    if (arg === '--project-path') {
+      const nextArg = args[i + 1];
+      if (nextArg !== undefined && !nextArg.startsWith('-')) {
+        options.projectPath = nextArg;
+      }
+      continue;
+    }
+
+    if (arg.startsWith('--project-path=')) {
+      options.projectPath = arg.slice('--project-path='.length);
+      continue;
+    }
+  }
+
+  return options;
+}
+
 /**
  * Main entry point with auto-sync for unknown commands.
  */
@@ -766,6 +811,7 @@ async function main(): Promise<void> {
 
   const args = process.argv.slice(2);
   const cmdName = args.find((arg) => !arg.startsWith('-'));
+  const syncGlobalOptions = extractSyncGlobalOptions(args);
 
   if (!shouldSkipAutoSync(cmdName, args)) {
     // Check if cache version is outdated and auto-sync if needed
@@ -775,7 +821,7 @@ async function main(): Promise<void> {
         `\x1b[33mCache outdated (${cachedVersion} → ${VERSION}). Syncing tools from Unity...\x1b[0m`,
       );
       try {
-        await syncTools({});
+        await syncTools(syncGlobalOptions);
         console.log('\x1b[32m✓ Tools synced successfully.\x1b[0m\n');
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -800,7 +846,7 @@ async function main(): Promise<void> {
   if (cmdName && !commandExists(cmdName)) {
     console.log(`\x1b[33mUnknown command '${cmdName}'. Syncing tools from Unity...\x1b[0m`);
     try {
-      await syncTools({});
+      await syncTools(syncGlobalOptions);
       const newCache = loadToolsCache();
       const tool = newCache.tools.find((t) => t.name === cmdName);
       if (tool) {

package/src/commands/focus-window.ts

@@ -10,13 +10,31 @@
 import { Command } from 'commander';
 import { findRunningUnityProcess, focusUnityProcess } from 'launch-unity';
 import { findUnityProjectRoot } from '../project-root.js';
+import { validateProjectPath } from '../port-resolver.js';
 
 export function registerFocusWindowCommand(program: Command): void {
   program
     .command('focus-window')
     .description('Bring Unity Editor window to front using OS-level commands')
-    .action(async () => {
-      const projectRoot = findUnityProjectRoot();
+    .option('--project-path <path>', 'Unity project path')
+    .action(async (options: { projectPath?: string }) => {
+      let projectRoot: string | null;
+      if (options.projectPath !== undefined) {
+        try {
+          projectRoot = validateProjectPath(options.projectPath);
+        } catch (error) {
+          console.error(
+            JSON.stringify({
+              Success: false,
+              Message: error instanceof Error ? error.message : String(error),
+            }),
+          );
+          process.exit(1);
+          return;
+        }
+      } else {
+        projectRoot = findUnityProjectRoot();
+      }
       if (projectRoot === null) {
         console.error(
           JSON.stringify({

package/src/commands/launch.ts

@@ -14,6 +14,7 @@ import { orchestrateLaunch } from 'launch-unity';
 interface LaunchCommandOptions {
   restart?: boolean;
   quit?: boolean;
+  deleteRecovery?: boolean;
   platform?: string;
   maxDepth?: string;
   addUnityHub?: boolean;
@@ -30,6 +31,7 @@ export function registerLaunchCommand(program: Command): void {
     )
     .argument('[project-path]', 'Path to Unity project')
     .option('-r, --restart', 'Kill running Unity and restart')
+    .option('-d, --delete-recovery', 'Delete Assets/_Recovery before launch')
     .option('-q, --quit', 'Gracefully quit running Unity')
     .option('-p, --platform <platform>', 'Build target (e.g., Android, iOS)')
     .option('--max-depth <n>', 'Search depth when project-path is omitted', '3')
@@ -66,6 +68,7 @@ async function runLaunchCommand(
     unityArgs: [],
     restart: options.restart === true,
     quit: options.quit === true,
+    deleteRecovery: options.deleteRecovery === true,
     addUnityHub: options.addUnityHub === true,
     favoriteUnityHub: options.favorite === true,
   });

package/src/compile-helpers.ts

@@ -0,0 +1,291 @@
+/**
+ * Compile-related helpers duplicated from TypeScriptServer~ to avoid cross-project imports
+ * that violate CLI's rootDir boundary (TS6059).
+ *
+ * Source: TypeScriptServer~/src/compile/compile-domain-reload-helpers.ts
+ */
+
+// CLI tools output to console by design, object keys come from Unity tool responses which are trusted,
+// and lock file paths are constructed from trusted project root detection
+/* eslint-disable security/detect-object-injection, security/detect-non-literal-fs-filename */
+
+import assert from 'node:assert';
+import { existsSync, readFileSync } from 'fs';
+import * as net from 'net';
+import { join } from 'path';
+
+// Only alphanumeric, underscore, and hyphen — blocks path separators and traversal sequences
+const SAFE_REQUEST_ID_PATTERN: RegExp = /^[a-zA-Z0-9_-]+$/;
+
+export const COMPILE_FORCE_RECOMPILE_ARG_KEYS = [
+  'ForceRecompile',
+  'forceRecompile',
+  'force_recompile',
+  'force-recompile',
+] as const;
+
+export const COMPILE_WAIT_FOR_DOMAIN_RELOAD_ARG_KEYS = [
+  'WaitForDomainReload',
+  'waitForDomainReload',
+  'wait_for_domain_reload',
+  'wait-for-domain-reload',
+] as const;
+
+export interface CompileExecutionOptions {
+  forceRecompile: boolean;
+  waitForDomainReload: boolean;
+}
+
+export interface CompileCompletionWaitOptions {
+  projectRoot: string;
+  requestId: string;
+  timeoutMs: number;
+  pollIntervalMs: number;
+  unityPort?: number;
+  isUnityReadyWhenIdle?: () => Promise<boolean>;
+}
+
+export type CompileCompletionOutcome = 'completed' | 'timed_out';
+
+export interface CompileCompletionResult<T> {
+  outcome: CompileCompletionOutcome;
+  result?: T;
+}
+
+/**
+ * Between compilationFinished and beforeAssemblyReload, there is a brief gap (~50ms measured)
+ * where no lock files exist. This grace period prevents false "completed" detection during that gap.
+ */
+const LOCK_GRACE_PERIOD_MS = 500;
+
+const READINESS_CHECK_TIMEOUT_MS = 3000;
+const DEFAULT_HOST = '127.0.0.1';
+const CONTENT_LENGTH_HEADER = 'Content-Length:';
+const HEADER_SEPARATOR = '\r\n\r\n';
+
+function toBoolean(value: unknown): boolean {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    return value.toLowerCase() === 'true';
+  }
+
+  return false;
+}
+
+function getCompileBooleanArg(args: Record<string, unknown>, keys: readonly string[]): boolean {
+  for (const key of keys) {
+    if (!(key in args)) {
+      continue;
+    }
+
+    return toBoolean(args[key]);
+  }
+
+  return false;
+}
+
+export function resolveCompileExecutionOptions(
+  args: Record<string, unknown>,
+): CompileExecutionOptions {
+  return {
+    forceRecompile: getCompileBooleanArg(args, COMPILE_FORCE_RECOMPILE_ARG_KEYS),
+    waitForDomainReload: getCompileBooleanArg(args, COMPILE_WAIT_FOR_DOMAIN_RELOAD_ARG_KEYS),
+  };
+}
+
+function createCompileRequestId(): string {
+  const timestamp = Date.now();
+  const randomToken = Math.floor(Math.random() * 1000000)
+    .toString()
+    .padStart(6, '0');
+  return `compile_${timestamp}_${randomToken}`;
+}
+
+export function ensureCompileRequestId(args: Record<string, unknown>): string {
+  const existingRequestId = args['RequestId'];
+  if (typeof existingRequestId === 'string' && existingRequestId.length > 0) {
+    if (SAFE_REQUEST_ID_PATTERN.test(existingRequestId)) {
+      return existingRequestId;
+    }
+  }
+
+  const requestId: string = createCompileRequestId();
+  args['RequestId'] = requestId;
+  return requestId;
+}
+
+function getCompileResultFilePath(projectRoot: string, requestId: string): string {
+  assert(
+    SAFE_REQUEST_ID_PATTERN.test(requestId),
+    `requestId contains unsafe characters: '${requestId}'`,
+  );
+  return join(projectRoot, 'Temp', 'uLoopMCP', 'compile-results', `${requestId}.json`);
+}
+
+function isUnityBusyByLockFiles(projectRoot: string): boolean {
+  const compilingLockPath = join(projectRoot, 'Temp', 'compiling.lock');
+  if (existsSync(compilingLockPath)) {
+    return true;
+  }
+
+  const domainReloadLockPath = join(projectRoot, 'Temp', 'domainreload.lock');
+  if (existsSync(domainReloadLockPath)) {
+    return true;
+  }
+
+  const serverStartingLockPath = join(projectRoot, 'Temp', 'serverstarting.lock');
+  return existsSync(serverStartingLockPath);
+}
+
+function stripUtf8Bom(content: string): string {
+  if (content.charCodeAt(0) === 0xfeff) {
+    return content.slice(1);
+  }
+
+  return content;
+}
+
+function tryReadCompileResult<T>(projectRoot: string, requestId: string): T | undefined {
+  const resultFilePath = getCompileResultFilePath(projectRoot, requestId);
+  if (!existsSync(resultFilePath)) {
+    return undefined;
+  }
+
+  try {
+    const content = readFileSync(resultFilePath, 'utf-8');
+    const parsed = JSON.parse(stripUtf8Bom(content)) as unknown;
+    return parsed as T;
+  } catch {
+    // File may be partially written by Unity or deleted between existsSync and readFileSync (TOCTOU).
+    // Return undefined so the polling loop retries on the next tick.
+    return undefined;
+  }
+}
+
+/**
+ * Verify Unity server can actually process a JSON-RPC request, not just accept TCP.
+ * Sends a lightweight get-tool-details request and waits for any valid framed response.
+ */
+function canSendRequestToUnity(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, READINESS_CHECK_TIMEOUT_MS);
+
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      socket.destroy();
+    };
+
+    socket.connect(port, DEFAULT_HOST, () => {
+      const rpcRequest: string = JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'get-tool-details',
+        params: { IncludeDevelopmentOnly: false },
+        id: 0,
+      });
+      const contentLength: number = Buffer.byteLength(rpcRequest, 'utf8');
+      const frame: string = `${CONTENT_LENGTH_HEADER} ${contentLength}${HEADER_SEPARATOR}${rpcRequest}`;
+      socket.write(frame);
+    });
+
+    let buffer: Buffer = Buffer.alloc(0);
+    socket.on('data', (chunk: Buffer) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      const sepIndex: number = buffer.indexOf(HEADER_SEPARATOR);
+      if (sepIndex !== -1) {
+        cleanup();
+        resolve(true);
+      }
+    });
+
+    socket.on('error', () => {
+      cleanup();
+      resolve(false);
+    });
+
+    socket.on('close', () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+  });
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Wait until the compile result file exists AND all Unity lock files are gone.
+ * After the result file appears and locks disappear, waits an additional grace period
+ * to catch the gap between compilationFinished and beforeAssemblyReload (~50ms measured).
+ */
+export async function waitForCompileCompletion<T>(
+  options: CompileCompletionWaitOptions,
+): Promise<CompileCompletionResult<T>> {
+  const startTime: number = Date.now();
+  let idleSinceTimestamp: number | null = null;
+
+  while (Date.now() - startTime < options.timeoutMs) {
+    const result: T | undefined = tryReadCompileResult<T>(options.projectRoot, options.requestId);
+    const isBusy: boolean = isUnityBusyByLockFiles(options.projectRoot);
+
+    if (result !== undefined && !isBusy) {
+      const now: number = Date.now();
+      if (idleSinceTimestamp === null) {
+        idleSinceTimestamp = now;
+      }
+
+      const idleDuration: number = now - idleSinceTimestamp;
+      if (idleDuration >= LOCK_GRACE_PERIOD_MS) {
+        if (options.unityPort !== undefined) {
+          const isReady: boolean = await canSendRequestToUnity(options.unityPort);
+          if (isReady) {
+            return { outcome: 'completed', result };
+          }
+        } else if (options.isUnityReadyWhenIdle) {
+          const isReady: boolean = await options.isUnityReadyWhenIdle();
+          if (isReady) {
+            return { outcome: 'completed', result };
+          }
+        } else {
+          return { outcome: 'completed', result };
+        }
+      }
+    } else {
+      idleSinceTimestamp = null;
+    }
+
+    await sleep(options.pollIntervalMs);
+  }
+
+  const lastResult: T | undefined = tryReadCompileResult<T>(options.projectRoot, options.requestId);
+  if (lastResult !== undefined && !isUnityBusyByLockFiles(options.projectRoot)) {
+    // Guard the compilationFinished→beforeAssemblyReload gap, same as the main loop
+    await sleep(LOCK_GRACE_PERIOD_MS);
+    if (isUnityBusyByLockFiles(options.projectRoot)) {
+      return { outcome: 'timed_out' };
+    }
+
+    if (options.unityPort !== undefined) {
+      const isReady: boolean = await canSendRequestToUnity(options.unityPort);
+      if (isReady) {
+        return { outcome: 'completed', result: lastResult };
+      }
+    } else if (options.isUnityReadyWhenIdle) {
+      const isReady: boolean = await options.isUnityReadyWhenIdle();
+      if (isReady) {
+        return { outcome: 'completed', result: lastResult };
+      }
+    } else {
+      return { outcome: 'completed', result: lastResult };
+    }
+  }
+
+  return { outcome: 'timed_out' };
+}

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.64.1",
+  "version": "0.66.0",
   "tools": [
     {
       "name": "compile",
@@ -10,6 +10,10 @@
           "ForceRecompile": {
             "type": "boolean",
             "description": "Force full recompilation"
+          },
+          "WaitForDomainReload": {
+            "type": "boolean",
+            "description": "Wait for domain reload completion before returning"
           }
         }
       }

package/src/direct-unity-client.ts

@@ -72,7 +72,16 @@ export class DirectUnityClient {
 
     return new Promise((resolve, reject) => {
       const socket = this.socket!;
+
+      const cleanup = (): void => {
+        clearTimeout(timeoutId);
+        socket.off('data', onData);
+        socket.off('error', onError);
+        socket.off('close', onClose);
+      };
+
       const timeoutId = setTimeout(() => {
+        cleanup();
         reject(
           new Error(
             `Request timed out after ${NETWORK_TIMEOUT_MS}ms. Unity may be frozen or busy. [For AI] Run 'uloop focus-window' to bring Unity to the front, then retry the tool. If the issue persists, report this to the user and ask how to proceed. Do NOT kill Unity processes without user permission.`,
@@ -98,9 +107,7 @@ export class DirectUnityClient {
           return;
         }
 
-        clearTimeout(timeoutId);
-        socket.off('data', onData);
-
+        cleanup();
         this.receiveBuffer = extractResult.remainingData;
 
         const response = JSON.parse(extractResult.jsonContent) as JsonRpcResponse;
@@ -113,7 +120,19 @@ export class DirectUnityClient {
         resolve(response.result as T);
       };
 
+      const onError = (error: Error): void => {
+        cleanup();
+        reject(new Error(`Connection lost: ${error.message}`));
+      };
+
+      const onClose = (): void => {
+        cleanup();
+        reject(new Error('UNITY_NO_RESPONSE'));
+      };
+
       socket.on('data', onData);
+      socket.on('error', onError);
+      socket.on('close', onClose);
       socket.write(framedMessage);
     });
   }