uloop-cli 1.7.0 → 1.7.3

package/src/__tests__/unity-process.test.ts

@@ -0,0 +1,289 @@
+import {
+  buildUnityProcessCommand,
+  extractUnityProjectPath,
+  findRunningUnityProcessForProject,
+  isUnityEditorProcess,
+  isUnityProcessForProject,
+  normalizeUnityProjectPath,
+  parseUnityProcesses,
+  tokenizeCommandLine,
+} from '../unity-process.js';
+
+describe('buildUnityProcessCommand', () => {
+  it('builds ps command for macOS', () => {
+    expect(buildUnityProcessCommand('darwin')).toEqual({
+      command: 'ps',
+      args: ['-Ao', 'pid=,command='],
+    });
+  });
+
+  it('builds powershell command for Windows', () => {
+    expect(buildUnityProcessCommand('win32')).toEqual({
+      command: 'powershell.exe',
+      args: [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Get-CimInstance Win32_Process -Filter "name = \'Unity.exe\'" | Select-Object ProcessId, CommandLine | ConvertTo-Json -Compress',
+      ],
+    });
+  });
+});
+
+describe('tokenizeCommandLine', () => {
+  it('keeps quoted project path as one token', () => {
+    expect(
+      tokenizeCommandLine(
+        '/Applications/Unity.app/Contents/MacOS/Unity -projectPath "/Users/me/My Project"',
+      ),
+    ).toEqual([
+      '/Applications/Unity.app/Contents/MacOS/Unity',
+      '-projectPath',
+      '/Users/me/My Project',
+    ]);
+  });
+});
+
+describe('extractUnityProjectPath', () => {
+  it('extracts macOS project path', () => {
+    expect(
+      extractUnityProjectPath(
+        '/Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/project',
+      ),
+    ).toBe('/Users/me/project');
+  });
+
+  it('extracts Windows project path case-insensitively', () => {
+    expect(
+      extractUnityProjectPath(
+        'C:\\Program Files\\Unity\\Editor\\Unity.exe -projectpath "C:\\Work\\My Project"',
+      ),
+    ).toBe('C:\\Work\\My Project');
+  });
+});
+
+describe('normalizeUnityProjectPath', () => {
+  it('normalizes Windows paths case-insensitively', () => {
+    expect(normalizeUnityProjectPath('C:\\Work\\My Project\\', 'win32')).toBe('c:/work/my project');
+  });
+});
+
+describe('parseUnityProcesses', () => {
+  it('parses ps output', () => {
+    expect(
+      parseUnityProcesses(
+        'darwin',
+        '123 /Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/project\n',
+      ),
+    ).toEqual([
+      {
+        pid: 123,
+        commandLine: '/Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/project',
+      },
+    ]);
+  });
+
+  it('parses Windows powershell JSON array output', () => {
+    expect(
+      parseUnityProcesses(
+        'win32',
+        '[{"ProcessId":101,"CommandLine":"C:\\\\Program Files\\\\Unity\\\\Editor\\\\Unity.exe -projectPath \\"C:\\\\Work\\\\Project A\\""}]',
+      ),
+    ).toEqual([
+      {
+        pid: 101,
+        commandLine:
+          'C:\\Program Files\\Unity\\Editor\\Unity.exe -projectPath "C:\\Work\\Project A"',
+      },
+    ]);
+  });
+
+  it('returns empty array when Windows output is empty', () => {
+    expect(parseUnityProcesses('win32', '')).toEqual([]);
+  });
+});
+
+describe('isUnityProcessForProject', () => {
+  it('matches project path on macOS', () => {
+    expect(
+      isUnityProcessForProject(
+        '/Applications/Unity.app/Contents/MacOS/Unity -projectPath "/Users/me/Project A"',
+        '/Users/me/Project A',
+        'darwin',
+      ),
+    ).toBe(true);
+  });
+
+  it('matches a macOS project path even when ps output has flattened quotes', () => {
+    expect(
+      isUnityProcessForProject(
+        '/Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/My Project',
+        '/Users/me/My Project',
+        'darwin',
+      ),
+    ).toBe(true);
+  });
+
+  it('matches a macOS project path when ps output keeps trailing slashes', () => {
+    expect(
+      isUnityProcessForProject(
+        '/Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/My Project/',
+        '/Users/me/My Project',
+        'darwin',
+      ),
+    ).toBe(true);
+  });
+
+  it('matches a macOS project path when ps output keeps repeated trailing slashes', () => {
+    expect(
+      isUnityProcessForProject(
+        '/Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/My Project///',
+        '/Users/me/My Project',
+        'darwin',
+      ),
+    ).toBe(true);
+  });
+
+  it('does not match a different macOS project that only shares the prefix', () => {
+    expect(
+      isUnityProcessForProject(
+        '/Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/My Project Backup',
+        '/Users/me/My Project',
+        'darwin',
+      ),
+    ).toBe(false);
+  });
+
+  it('matches project path on Windows case-insensitively', () => {
+    expect(
+      isUnityProcessForProject(
+        'C:\\Program Files\\Unity\\Editor\\Unity.exe -projectPath "C:\\Work\\Project A"',
+        'c:/work/project a',
+        'win32',
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('isUnityEditorProcess', () => {
+  it('detects the Unity editor on macOS', () => {
+    expect(
+      isUnityEditorProcess(
+        '/Applications/Unity/Hub/Editor/2022.3.62f3/Unity.app/Contents/MacOS/Unity -projectPath "/Users/me/Project A"',
+        'darwin',
+      ),
+    ).toBe(true);
+  });
+
+  it('rejects a non-Unity process on macOS even when projectPath is present', () => {
+    expect(
+      isUnityEditorProcess(
+        '/usr/local/bin/custom-tool -projectPath "/Users/me/Project A"',
+        'darwin',
+      ),
+    ).toBe(false);
+  });
+
+  it('detects the Unity editor on Windows without relying on command line casing', () => {
+    expect(
+      isUnityEditorProcess(
+        'C:\\Program Files\\Unity\\Editor\\UNITY.EXE -projectPath "C:\\Work\\Project A"',
+        'win32',
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('findRunningUnityProcessForProject', () => {
+  it('returns null when no Unity process is running', async () => {
+    const runCommand = jest.fn<Promise<string>, [string, string[]]>().mockResolvedValue('');
+
+    await expect(
+      findRunningUnityProcessForProject('/Users/me/project', {
+        platform: 'darwin',
+        runCommand,
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it('returns matching Unity process on macOS', async () => {
+    const runCommand = jest
+      .fn<Promise<string>, [string, string[]]>()
+      .mockResolvedValue(
+        [
+          '111 /Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/other',
+          '222 /Applications/Unity.app/Contents/MacOS/Unity -projectPath "/Users/me/project"',
+        ].join('\n'),
+      );
+
+    await expect(
+      findRunningUnityProcessForProject('/Users/me/project', {
+        platform: 'darwin',
+        runCommand,
+      }),
+    ).resolves.toEqual({ pid: 222 });
+  });
+
+  it('returns a matching macOS Unity process when ps output has flattened quotes', async () => {
+    const runCommand = jest
+      .fn<Promise<string>, [string, string[]]>()
+      .mockResolvedValue(
+        '222 /Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/My Project',
+      );
+
+    await expect(
+      findRunningUnityProcessForProject('/Users/me/My Project', {
+        platform: 'darwin',
+        runCommand,
+      }),
+    ).resolves.toEqual({ pid: 222 });
+  });
+
+  it('returns a matching macOS Unity process when ps output keeps trailing slashes', async () => {
+    const runCommand = jest
+      .fn<Promise<string>, [string, string[]]>()
+      .mockResolvedValue(
+        '222 /Applications/Unity.app/Contents/MacOS/Unity -projectPath /Users/me/My Project///',
+      );
+
+    await expect(
+      findRunningUnityProcessForProject('/Users/me/My Project', {
+        platform: 'darwin',
+        runCommand,
+      }),
+    ).resolves.toEqual({ pid: 222 });
+  });
+
+  it('ignores non-Unity processes that happen to share the same projectPath', async () => {
+    const runCommand = jest
+      .fn<Promise<string>, [string, string[]]>()
+      .mockResolvedValue(
+        [
+          '111 /usr/local/bin/custom-tool -projectPath "/Users/me/project"',
+          '222 /Applications/Unity.app/Contents/MacOS/Unity -projectPath "/Users/me/project"',
+        ].join('\n'),
+      );
+
+    await expect(
+      findRunningUnityProcessForProject('/Users/me/project', {
+        platform: 'darwin',
+        runCommand,
+      }),
+    ).resolves.toEqual({ pid: 222 });
+  });
+
+  it('returns matching Unity process on Windows', async () => {
+    const runCommand = jest
+      .fn<Promise<string>, [string, string[]]>()
+      .mockResolvedValue(
+        '[{"ProcessId":333,"CommandLine":"C:\\\\Program Files\\\\Unity\\\\Editor\\\\UNITY.EXE -projectPath \\"C:\\\\Work\\\\My Project\\""}]',
+      );
+
+    await expect(
+      findRunningUnityProcessForProject('c:/work/my project', {
+        platform: 'win32',
+        runCommand,
+      }),
+    ).resolves.toEqual({ pid: 333 });
+  });
+});

package/src/cli-project-error.ts

@@ -0,0 +1,36 @@
+import { UnityNotRunningError, UnityServerNotRunningError } from './port-resolver.js';
+import { ProjectMismatchError } from './project-validator.js';
+
+export function getProjectResolutionErrorLines(
+  error: UnityNotRunningError | UnityServerNotRunningError | ProjectMismatchError,
+): string[] {
+  if (error instanceof UnityServerNotRunningError) {
+    return [
+      'Error: Unity Editor is running, but Unity CLI Loop server is not.',
+      '',
+      `  Project: ${error.projectRoot}`,
+      '',
+      'Start the server from: Window > Unity CLI Loop > Server',
+    ];
+  }
+
+  if (error instanceof UnityNotRunningError) {
+    return [
+      'Error: Unity Editor for this project is not running.',
+      '',
+      `  Project: ${error.projectRoot}`,
+      '',
+      'Start the Unity Editor for this project and try again.',
+    ];
+  }
+
+  return [
+    'Error: Connected Unity instance belongs to a different project.',
+    '',
+    `  Project:      ${error.expectedProjectRoot}`,
+    `  Connected to: ${error.connectedProjectRoot}`,
+    '',
+    'Another Unity instance was found, but it belongs to a different project.',
+    'Start the Unity Editor for this project, or use --project-path to specify the target.',
+  ];
+}

package/src/cli.ts

@@ -36,9 +36,14 @@ 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, UnityNotRunningError } from './port-resolver.js';
+import {
+  validateProjectPath,
+  UnityNotRunningError,
+  UnityServerNotRunningError,
+} from './port-resolver.js';
 import { ProjectMismatchError } from './project-validator.js';
 import { filterEnabledTools, isToolEnabled } from './tool-settings-loader.js';
+import { getProjectResolutionErrorLines } from './cli-project-error.js';
 
 interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
@@ -429,25 +434,17 @@ async function runWithErrorHandling(fn: () => Promise<void>): Promise<void> {
   try {
     await fn();
   } catch (error) {
-    if (error instanceof UnityNotRunningError) {
-      console.error('\x1b[31mError: Unity Editor for this project is not running.\x1b[0m');
-      console.error('');
-      console.error(`  Project: ${error.projectRoot}`);
-      console.error('');
-      console.error('Start the Unity Editor for this project and try again.');
+    if (error instanceof UnityNotRunningError || error instanceof UnityServerNotRunningError) {
+      for (const line of getProjectResolutionErrorLines(error)) {
+        console.error(line.startsWith('Error: ') ? `\x1b[31m${line}\x1b[0m` : line);
+      }
       process.exit(1);
     }
 
     if (error instanceof ProjectMismatchError) {
-      console.error('\x1b[31mError: Unity Editor for this project is not running.\x1b[0m');
-      console.error('');
-      console.error(`  Project:      ${error.expectedProjectRoot}`);
-      console.error(`  Connected to: ${error.connectedProjectRoot}`);
-      console.error('');
-      console.error('Another Unity instance was found, but it belongs to a different project.');
-      console.error(
-        'Start the Unity Editor for this project, or use --project-path to specify the target.',
-      );
+      for (const line of getProjectResolutionErrorLines(error)) {
+        console.error(line.startsWith('Error: ') ? `\x1b[31m${line}\x1b[0m` : line);
+      }
       process.exit(1);
     }
 
@@ -604,11 +601,9 @@ compdef _uloop uloop`;
 /**
  * Get the currently installed version of uloop-cli from npm.
  */
-function getInstalledVersion(callback: (version: string | null) => void): void {
+export function getInstalledVersion(callback: (version: string | null) => void): void {
   const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const child = spawn(npmCommand, ['list', '-g', 'uloop-cli', '--json'], {
-    shell: true,
-  });
+  const child = spawn(npmCommand, ['list', '-g', 'uloop-cli', '--json']);
 
   let stdout = '';
   child.stdout.on('data', (data: Buffer) => {
@@ -663,14 +658,13 @@ function getInstalledVersion(callback: (version: string | null) => void): void {
 /**
  * Update uloop CLI to the latest version using npm.
  */
-function updateCli(): void {
+export function updateCli(): void {
   const previousVersion = VERSION;
   console.log('Updating uloop-cli to the latest version...');
 
   const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
   const child = spawn(npmCommand, ['install', '-g', 'uloop-cli@latest'], {
     stdio: 'inherit',
-    shell: true,
   });
 
   child.on('close', (code) => {
@@ -1039,4 +1033,6 @@ async function main(): Promise<void> {
   program.parse();
 }
 
-void main();
+if (process.env.JEST_WORKER_ID === undefined) {
+  void main();
+}

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.7.0",
+  "version": "1.7.3",
   "tools": [
     {
       "name": "compile",

package/src/execute-tool.ts

@@ -13,12 +13,18 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import * as semver from 'semver';
 import { DirectUnityClient } from './direct-unity-client.js';
-import { resolveUnityPort, validateProjectPath } from './port-resolver.js';
+import {
+  resolveUnityPort,
+  UnityNotRunningError,
+  UnityServerNotRunningError,
+  validateProjectPath,
+} from './port-resolver.js';
 import { validateConnectedProject } from './project-validator.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 { findRunningUnityProcessForProject } from './unity-process.js';
 import {
   type CompileExecutionOptions,
   ensureCompileRequestId,
@@ -77,6 +83,14 @@ const MAX_RETRIES = 3;
 const COMPILE_WAIT_TIMEOUT_MS = 90000;
 const COMPILE_WAIT_POLL_INTERVAL_MS = 100;
 
+interface ConnectionFailureDiagnosisDependencies {
+  findRunningUnityProcessForProjectFn: typeof findRunningUnityProcessForProject;
+}
+
+const defaultConnectionFailureDiagnosisDependencies: ConnectionFailureDiagnosisDependencies = {
+  findRunningUnityProcessForProjectFn: findRunningUnityProcessForProject,
+};
+
 function getCompileExecutionOptions(
   toolName: string,
   params: Record<string, unknown>,
@@ -103,6 +117,54 @@ function isRetryableError(error: unknown): boolean {
   );
 }
 
+export async function diagnoseRetryableProjectConnectionError(
+  error: unknown,
+  projectRoot: string | null,
+  shouldDiagnoseProjectState: boolean,
+  dependencies: ConnectionFailureDiagnosisDependencies = defaultConnectionFailureDiagnosisDependencies,
+): Promise<unknown> {
+  if (!shouldDiagnoseProjectState || projectRoot === null || !isRetryableError(error)) {
+    return error;
+  }
+
+  const runningProcess = await dependencies
+    .findRunningUnityProcessForProjectFn(projectRoot)
+    .catch(() => undefined);
+
+  if (runningProcess === undefined) {
+    return error;
+  }
+
+  if (runningProcess === null) {
+    return new UnityNotRunningError(projectRoot);
+  }
+
+  return new UnityServerNotRunningError(projectRoot);
+}
+
+async function throwFinalToolError(
+  error: unknown,
+  projectRoot: string | null,
+  shouldDiagnoseProjectState: boolean,
+): Promise<never> {
+  const diagnosedError = await diagnoseRetryableProjectConnectionError(
+    error,
+    projectRoot,
+    shouldDiagnoseProjectState,
+  );
+
+  if (diagnosedError instanceof Error) {
+    throw diagnosedError;
+  }
+
+  if (typeof diagnosedError === 'string') {
+    throw new Error(diagnosedError);
+  }
+
+  const serializedError = JSON.stringify(diagnosedError);
+  throw new Error(serializedError ?? 'Unknown error');
+}
+
 // 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
@@ -188,6 +250,14 @@ function checkUnityBusyState(projectPath?: string): void {
   }
 }
 
+function checkUnityBusyStateBeforeProjectResolution(globalOptions: GlobalOptions): void {
+  if (globalOptions.port !== undefined) {
+    return;
+  }
+
+  checkUnityBusyState(globalOptions.projectPath);
+}
+
 export async function executeToolCommand(
   toolName: string,
   params: Record<string, unknown>,
@@ -201,6 +271,7 @@ export async function executeToolCommand(
     }
     portNumber = parsed;
   }
+  checkUnityBusyStateBeforeProjectResolution(globalOptions);
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
   const compileOptions = getCompileExecutionOptions(toolName, params);
   const shouldWaitForDomainReload = compileOptions.waitForDomainReload;
@@ -228,7 +299,7 @@ export async function executeToolCommand(
   let requestDispatched = false;
 
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState(globalOptions.projectPath);
+    checkUnityBusyStateBeforeProjectResolution(globalOptions);
 
     const client = new DirectUnityClient(port);
     try {
@@ -308,8 +379,8 @@ export async function executeToolCommand(
     if (immediateResult === undefined && !requestDispatched) {
       spinner.stop();
       restoreStdin();
-      if (lastError instanceof Error) {
-        throw lastError;
+      if (lastError !== undefined) {
+        await throwFinalToolError(lastError, projectRoot, shouldValidateProject);
       }
       throw new Error(
         'Compile request never reached Unity. Check that Unity is running and retry.',
@@ -371,15 +442,7 @@ export async function executeToolCommand(
   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');
+  await throwFinalToolError(lastError, projectRoot, shouldValidateProject);
 }
 
 export async function listAvailableTools(globalOptions: GlobalOptions): Promise<void> {
@@ -391,6 +454,7 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
     }
     portNumber = parsed;
   }
+  checkUnityBusyStateBeforeProjectResolution(globalOptions);
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
   const projectRoot =
     globalOptions.projectPath !== undefined
@@ -403,7 +467,7 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState(globalOptions.projectPath);
+    checkUnityBusyStateBeforeProjectResolution(globalOptions);
 
     const client = new DirectUnityClient(port);
     try {
@@ -445,7 +509,7 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
 
   spinner.stop();
   restoreStdin();
-  throw lastError;
+  await throwFinalToolError(lastError, projectRoot, shouldValidateProject);
 }
 
 interface UnityToolInfo {
@@ -488,6 +552,7 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
     }
     portNumber = parsed;
   }
+  checkUnityBusyStateBeforeProjectResolution(globalOptions);
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
   const projectRoot =
     globalOptions.projectPath !== undefined
@@ -500,7 +565,7 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState(globalOptions.projectPath);
+    checkUnityBusyStateBeforeProjectResolution(globalOptions);
 
     const client = new DirectUnityClient(port);
     try {
@@ -562,5 +627,5 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
 
   spinner.stop();
   restoreStdin();
-  throw lastError;
+  await throwFinalToolError(lastError, projectRoot, shouldValidateProject);
 }

package/src/port-resolver.ts

@@ -23,6 +23,12 @@ export class UnityNotRunningError extends Error {
   }
 }
 
+export class UnityServerNotRunningError extends Error {
+  constructor(public readonly projectRoot: string) {
+    super('UNITY_SERVER_NOT_RUNNING');
+  }
+}
+
 interface UnityMcpSettings {
   isServerRunning?: boolean;
   customPort?: number;
@@ -130,12 +136,6 @@ async function readPortFromSettingsOrThrow(projectRoot: string): Promise<number>
     }
     const settings = parsed as UnityMcpSettings;
 
-    // Only block when isServerRunning is explicitly false (Unity clean shutdown).
-    // undefined/missing means old settings format — proceed to next validation stage.
-    if (settings.isServerRunning === false) {
-      throw new UnityNotRunningError(projectRoot);
-    }
-
     const port = resolvePortFromUnitySettings(settings);
     if (port !== null) {
       return port;

package/src/project-root.ts

@@ -34,7 +34,7 @@ export function getUnitySettingsCandidatePaths(dirPath: string): string[] {
 }
 
 export function hasUloopInstalled(dirPath: string): boolean {
-  return getUnitySettingsCandidatePaths(dirPath).some(path => existsSync(path));
+  return getUnitySettingsCandidatePaths(dirPath).some((path) => existsSync(path));
 }
 
 function isUnityProjectWithUloop(dirPath: string): boolean {