uloop-cli 0.64.1 → 0.66.0

package/src/execute-tool.ts

@@ -12,11 +12,18 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import * as semver from 'semver';
 import { DirectUnityClient } from './direct-unity-client.js';
-import { resolveUnityPort } from './port-resolver.js';
+import { resolveUnityPort, validateProjectPath } from './port-resolver.js';
 import { saveToolsCache, getCacheFilePath, ToolsCache, ToolDefinition } from './tool-cache.js';
 import { VERSION } from './version.js';
 import { createSpinner } from './spinner.js';
 import { findUnityProjectRoot } from './project-root.js';
+import {
+  type CompileExecutionOptions,
+  ensureCompileRequestId,
+  resolveCompileExecutionOptions,
+  sleep,
+  waitForCompileCompletion,
+} from './compile-helpers.js';
 
 /**
  * Suppress stdin echo during async operation to prevent escape sequences from being displayed.
@@ -54,13 +61,32 @@ function suppressStdinEcho(): () => void {
 
 export interface GlobalOptions {
   port?: string;
+  projectPath?: string;
+}
+
+function stripInternalFields(result: Record<string, unknown>): Record<string, unknown> {
+  const cleaned = { ...result };
+  delete cleaned['ProjectRoot'];
+  return cleaned;
 }
 
 const RETRY_DELAY_MS = 500;
 const MAX_RETRIES = 3;
+const COMPILE_WAIT_TIMEOUT_MS = 90000;
+const COMPILE_WAIT_POLL_INTERVAL_MS = 100;
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function getCompileExecutionOptions(
+  toolName: string,
+  params: Record<string, unknown>,
+): CompileExecutionOptions {
+  if (toolName !== 'compile') {
+    return {
+      forceRecompile: false,
+      waitForDomainReload: false,
+    };
+  }
+
+  return resolveCompileExecutionOptions(params);
 }
 
 function isRetryableError(error: unknown): boolean {
@@ -75,6 +101,18 @@ function isRetryableError(error: unknown): boolean {
   );
 }
 
+// Distinct from isRetryableError(): that function covers pre-connection failures
+// (ECONNREFUSED, EADDRNOTAVAIL) which cannot occur after dispatch.
+// This function covers post-dispatch TCP failures where Unity may have received
+// the request but the response was lost — file-based recovery is appropriate.
+export function isTransportDisconnectError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const message: string = error.message;
+  return message === 'UNITY_NO_RESPONSE' || message.startsWith('Connection lost:');
+}
+
 /**
  * Compare two semantic versions safely.
  * Returns true if v1 < v2, false otherwise.
@@ -125,8 +163,9 @@ function checkServerVersion(result: Record<string, unknown>): void {
  * Check if Unity is in a busy state (compiling, reloading, or server starting).
  * Throws an error with appropriate message if busy.
  */
-function checkUnityBusyState(): void {
-  const projectRoot = findUnityProjectRoot();
+function checkUnityBusyState(projectPath?: string): void {
+  const projectRoot =
+    projectPath !== undefined ? validateProjectPath(projectPath) : findUnityProjectRoot();
   if (projectRoot === null) {
     return;
   }
@@ -160,39 +199,82 @@ export async function executeToolCommand(
     }
     portNumber = parsed;
   }
-  const port = await resolveUnityPort(portNumber);
+  const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
+  const compileOptions = getCompileExecutionOptions(toolName, params);
+  const shouldWaitForDomainReload = compileOptions.waitForDomainReload;
+  const compileRequestId = shouldWaitForDomainReload ? ensureCompileRequestId(params) : undefined;
 
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner('Connecting to Unity...');
 
   let lastError: unknown;
+  let immediateResult: Record<string, unknown> | undefined;
+  const projectRoot =
+    globalOptions.projectPath !== undefined
+      ? validateProjectPath(globalOptions.projectPath)
+      : findUnityProjectRoot();
+
+  // Monotonically-increasing flag: once true, retries cannot reset it to false.
+  // The retry loop overwrites `lastError` and `immediateResult` on each attempt,
+  // which destroys the evidence of whether an earlier attempt successfully dispatched
+  // the request to Unity. This flag preserves that information across retries.
+  // See: git log cb3d63e..HEAD for the history of oscillating fixes caused by
+  // inferring dispatch status from `immediateResult` alone.
+  let requestDispatched = false;
+
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState();
+    checkUnityBusyState(globalOptions.projectPath);
 
     const client = new DirectUnityClient(port);
     try {
       await client.connect();
 
       spinner.update(`Executing ${toolName}...`);
+      // connect() succeeded: socket is established. sendRequest() calls socket.write()
+      // synchronously (direct-unity-client.ts:136), so the data reaches the kernel
+      // send buffer before any async error can occur. Safe to mark as dispatched here.
+      requestDispatched = true;
       const result = await client.sendRequest<Record<string, unknown>>(toolName, params);
 
       if (result === undefined || result === null) {
         throw new Error('UNITY_NO_RESPONSE');
       }
 
-      // Success - stop spinner and output result
-      spinner.stop();
-      restoreStdin();
+      immediateResult = result;
+      if (!shouldWaitForDomainReload) {
+        spinner.stop();
+        restoreStdin();
 
-      // Check server version and warn if mismatched
-      checkServerVersion(result);
+        checkServerVersion(result);
+        console.log(JSON.stringify(stripInternalFields(result), null, 2));
+        return;
+      }
 
-      console.log(JSON.stringify(result, null, 2));
-      return;
+      break;
     } catch (error) {
       lastError = error;
       client.disconnect();
 
+      // After a compile request has been dispatched, retrying is counterproductive:
+      // the next loop iteration calls checkUnityBusyState() OUTSIDE the try block,
+      // which throws UNITY_DOMAIN_RELOAD during domain reload and escapes the
+      // entire function — bypassing waitForCompileCompletion() recovery.
+      if (requestDispatched && shouldWaitForDomainReload) {
+        if (isTransportDisconnectError(error)) {
+          // Unity may have received the request before the TCP drop.
+          // Break out of retry loop → proceed to file-based recovery below.
+          spinner.update('Connection lost during compile. Waiting for result file...');
+          break;
+        }
+        // JSON-RPC error (e.g. "Unity error: ..."): Unity processed the request
+        // and returned an explicit error. No result file will be written
+        // (confirmed: CompileUseCase.ExecuteAsync() is not reached when
+        // JSON-RPC error occurs at parameter validation / security check).
+        spinner.stop();
+        restoreStdin();
+        throw error instanceof Error ? error : new Error(String(error));
+      }
+
       if (!isRetryableError(error) || attempt >= MAX_RETRIES) {
         break;
       }
@@ -203,9 +285,92 @@ export async function executeToolCommand(
     }
   }
 
+  if (shouldWaitForDomainReload && compileRequestId) {
+    // Fail fast when the compile request never reached Unity.
+    // Without this guard, unreachable Unity would cause a 90-second wait for a
+    // result file that will never be created.
+    // We check both conditions because:
+    //  - immediateResult === undefined: no JSON-RPC response was received
+    //  - !requestDispatched: no attempt ever successfully connected and called sendRequest()
+    // If requestDispatched is true but immediateResult is undefined, the request was sent
+    // but the TCP connection dropped before the response arrived (domain reload scenario).
+    // In that case, Unity may have already written the result file, so we proceed to
+    // file-based polling recovery.
+    if (immediateResult === undefined && !requestDispatched) {
+      spinner.stop();
+      restoreStdin();
+      if (lastError instanceof Error) {
+        throw lastError;
+      }
+      throw new Error(
+        'Compile request never reached Unity. Check that Unity is running and retry.',
+      );
+    }
+
+    const projectRootFromUnity: string | undefined =
+      immediateResult !== undefined
+        ? (immediateResult['ProjectRoot'] as string | undefined)
+        : undefined;
+    const effectiveProjectRoot: string | null = projectRootFromUnity ?? projectRoot;
+
+    // File-based polling requires a known project root
+    if (effectiveProjectRoot === null) {
+      spinner.stop();
+      restoreStdin();
+      if (immediateResult !== undefined) {
+        checkServerVersion(immediateResult);
+        console.log(JSON.stringify(stripInternalFields(immediateResult), null, 2));
+        return;
+      }
+      if (lastError instanceof Error) {
+        throw lastError;
+      }
+      throw new Error(
+        'Compile request failed and project root is unknown. Check connection and retry.',
+      );
+    }
+
+    spinner.update('Waiting for domain reload to complete...');
+    const { outcome, result: storedResult } = await waitForCompileCompletion<
+      Record<string, unknown>
+    >({
+      projectRoot: effectiveProjectRoot,
+      requestId: compileRequestId,
+      timeoutMs: COMPILE_WAIT_TIMEOUT_MS,
+      pollIntervalMs: COMPILE_WAIT_POLL_INTERVAL_MS,
+      unityPort: port,
+    });
+
+    if (outcome === 'timed_out') {
+      lastError = new Error(
+        `Compile wait timed out after ${COMPILE_WAIT_TIMEOUT_MS}ms. Run 'uloop fix' and retry.`,
+      );
+    } else {
+      const finalResult = storedResult ?? immediateResult;
+      if (finalResult !== undefined) {
+        spinner.stop();
+        restoreStdin();
+        checkServerVersion(finalResult);
+        console.log(JSON.stringify(stripInternalFields(finalResult), null, 2));
+        return;
+      }
+    }
+  }
+
   spinner.stop();
   restoreStdin();
-  throw lastError;
+  if (lastError === undefined) {
+    throw new Error('Tool execution failed without error details.');
+  }
+  if (lastError instanceof Error) {
+    throw lastError;
+  }
+  if (typeof lastError === 'string') {
+    throw new Error(lastError);
+  }
+
+  const serializedError = JSON.stringify(lastError);
+  throw new Error(serializedError ?? 'Unknown error');
 }
 
 export async function listAvailableTools(globalOptions: GlobalOptions): Promise<void> {
@@ -217,14 +382,14 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
     }
     portNumber = parsed;
   }
-  const port = await resolveUnityPort(portNumber);
+  const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
 
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner('Connecting to Unity...');
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState();
+    checkUnityBusyState(globalOptions.projectPath);
 
     const client = new DirectUnityClient(port);
     try {
@@ -305,14 +470,14 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
     }
     portNumber = parsed;
   }
-  const port = await resolveUnityPort(portNumber);
+  const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
 
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner('Connecting to Unity...');
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState();
+    checkUnityBusyState(globalOptions.projectPath);
 
     const client = new DirectUnityClient(port);
     try {

package/src/port-resolver.ts

@@ -8,8 +8,8 @@
 
 import { readFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { join } from 'path';
-import { findUnityProjectRoot } from './project-root.js';
+import { join, resolve } from 'path';
+import { findUnityProjectRoot, isUnityProject, hasUloopInstalled } from './project-root.js';
 
 const DEFAULT_PORT = 8700;
 
@@ -54,14 +54,52 @@ export function resolvePortFromUnitySettings(settings: UnityMcpSettings): number
   return null;
 }
 
-export async function resolveUnityPort(explicitPort?: number): Promise<number> {
+export function validateProjectPath(projectPath: string): string {
+  const resolved = resolve(projectPath);
+
+  if (!existsSync(resolved)) {
+    throw new Error(`Path does not exist: ${resolved}`);
+  }
+
+  if (!isUnityProject(resolved)) {
+    throw new Error(`Not a Unity project (Assets/ or ProjectSettings/ not found): ${resolved}`);
+  }
+
+  if (!hasUloopInstalled(resolved)) {
+    throw new Error(
+      `uLoopMCP is not installed in this project (UserSettings/UnityMcpSettings.json not found): ${resolved}`,
+    );
+  }
+
+  return resolved;
+}
+
+export async function resolveUnityPort(
+  explicitPort?: number,
+  projectPath?: string,
+): Promise<number> {
+  if (explicitPort !== undefined && projectPath !== undefined) {
+    throw new Error('Cannot specify both --port and --project-path. Use one or the other.');
+  }
+
   if (explicitPort !== undefined) {
     return explicitPort;
   }
 
+  if (projectPath !== undefined) {
+    const resolved = validateProjectPath(projectPath);
+    const settingsPort = await readPortFromSettings(resolved);
+    if (settingsPort !== null) {
+      return settingsPort;
+    }
+    return DEFAULT_PORT;
+  }
+
   const projectRoot = findUnityProjectRoot();
   if (projectRoot === null) {
-    throw new Error('Unity project not found. Use --port option to specify the port explicitly.');
+    throw new Error(
+      'Unity project not found. Use --port or --project-path option to specify the target.',
+    );
   }
 
   const settingsPort = await readPortFromSettings(projectRoot);

package/src/project-root.ts

@@ -22,13 +22,13 @@ const EXCLUDED_DIRS = new Set([
   'Library',
 ]);
 
-function isUnityProject(dirPath: string): boolean {
+export function isUnityProject(dirPath: string): boolean {
   const hasAssets = existsSync(join(dirPath, 'Assets'));
   const hasProjectSettings = existsSync(join(dirPath, 'ProjectSettings'));
   return hasAssets && hasProjectSettings;
 }
 
-function hasUloopInstalled(dirPath: string): boolean {
+export function hasUloopInstalled(dirPath: string): boolean {
   return existsSync(join(dirPath, 'UserSettings/UnityMcpSettings.json'));
 }
 

package/src/skills/skill-definitions/cli-only/uloop-focus-window/SKILL.md

@@ -17,6 +17,13 @@ uloop focus-window
 
 None.
 
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--project-path <path>` | Target a specific Unity project (mutually exclusive with `--port`). Path resolution follows the same rules as `cd` — absolute paths are used as-is, relative paths are resolved from cwd. |
+| `-p, --port <port>` | Specify Unity TCP port directly (mutually exclusive with `--project-path`). |
+
 ## Examples
 
 ```bash

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.64.1'; // x-release-please-version
+export const VERSION = '0.66.0'; // x-release-please-version