uloop-cli 1.7.0 → 1.7.3

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "uloop-cli",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via Unity CLI Loop",
   "main": "dist/cli.bundle.cjs",
   "bin": {
-    "uloop": "./dist/cli.bundle.cjs"
+    "uloop": "dist/cli.bundle.cjs"
   },
   "type": "module",
   "scripts": {
@@ -49,7 +49,7 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/jest": "30.0.0",
-    "@types/node": "25.5.2",
+    "@types/node": "25.6.0",
     "@types/semver": "7.7.1",
     "esbuild": "0.28.0",
     "eslint": "10.2.0",
@@ -57,11 +57,11 @@
     "eslint-plugin-prettier": "5.5.5",
     "eslint-plugin-security": "4.0.0",
     "jest": "30.3.0",
-    "knip": "6.3.0",
-    "prettier": "3.8.1",
+    "knip": "6.3.1",
+    "prettier": "3.8.2",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.58.0"
+    "typescript-eslint": "8.58.1"
   },
   "overrides": {
     "minimatch": "10.2.4"

package/src/__tests__/busy-state-order.test.ts

@@ -0,0 +1,120 @@
+const mockResolveUnityPort = jest.fn<Promise<number>, [number | undefined, string | undefined]>();
+const mockValidateProjectPath = jest.fn<string, [string]>();
+const mockFindUnityProjectRoot = jest.fn<string | null, []>();
+const mockExistsSync = jest.fn<boolean, [string]>();
+
+jest.mock('../port-resolver.js', () => ({
+  resolveUnityPort: (explicitPort?: number, projectPath?: string): Promise<number> =>
+    mockResolveUnityPort(explicitPort, projectPath),
+  validateProjectPath: (projectPath: string): string => mockValidateProjectPath(projectPath),
+}));
+
+jest.mock('../project-root.js', () => ({
+  findUnityProjectRoot: (): string | null => mockFindUnityProjectRoot(),
+}));
+
+jest.mock('fs', () => ({
+  existsSync: (path: string): boolean => mockExistsSync(path),
+}));
+
+import { executeToolCommand, listAvailableTools, syncTools } from '../execute-tool.js';
+
+describe('busy state detection order', () => {
+  beforeEach(() => {
+    mockResolveUnityPort.mockReset();
+    mockResolveUnityPort.mockRejectedValue(new Error('RESOLVE_CALLED_BEFORE_BUSY_CHECK'));
+
+    mockValidateProjectPath.mockReset();
+    mockValidateProjectPath.mockReturnValue('/project');
+
+    mockFindUnityProjectRoot.mockReset();
+    mockFindUnityProjectRoot.mockReturnValue('/project');
+
+    mockExistsSync.mockReset();
+    mockExistsSync.mockImplementation((path: string) => path.endsWith('serverstarting.lock'));
+  });
+
+  it('checks busy state before resolving port for tool execution', async () => {
+    await expect(executeToolCommand('get-logs', {}, { projectPath: '/project' })).rejects.toThrow(
+      'UNITY_SERVER_STARTING',
+    );
+
+    expect(mockResolveUnityPort).not.toHaveBeenCalled();
+  });
+
+  it('checks busy state before resolving port for list', async () => {
+    await expect(listAvailableTools({ projectPath: '/project' })).rejects.toThrow(
+      'UNITY_SERVER_STARTING',
+    );
+
+    expect(mockResolveUnityPort).not.toHaveBeenCalled();
+  });
+
+  it('checks busy state before resolving port for sync', async () => {
+    await expect(syncTools({ projectPath: '/project' })).rejects.toThrow('UNITY_SERVER_STARTING');
+
+    expect(mockResolveUnityPort).not.toHaveBeenCalled();
+  });
+
+  it('skips busy state checks when an explicit port is provided for tool execution', async () => {
+    mockResolveUnityPort.mockRejectedValue(new Error('EXPLICIT_PORT_RESOLVED'));
+
+    await expect(executeToolCommand('get-logs', {}, { port: '8711' })).rejects.toThrow(
+      'EXPLICIT_PORT_RESOLVED',
+    );
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, undefined);
+  });
+
+  it('preserves usage errors before busy state checks for tool execution', async () => {
+    mockResolveUnityPort.mockRejectedValue(
+      new Error('Cannot specify both --port and --project-path. Use one or the other.'),
+    );
+
+    await expect(
+      executeToolCommand('get-logs', {}, { port: '8711', projectPath: '/project' }),
+    ).rejects.toThrow('Cannot specify both --port and --project-path. Use one or the other.');
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, '/project');
+  });
+
+  it('skips busy state checks when an explicit port is provided for list', async () => {
+    mockResolveUnityPort.mockRejectedValue(new Error('EXPLICIT_PORT_RESOLVED'));
+
+    await expect(listAvailableTools({ port: '8711' })).rejects.toThrow('EXPLICIT_PORT_RESOLVED');
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, undefined);
+  });
+
+  it('preserves usage errors before busy state checks for list', async () => {
+    mockResolveUnityPort.mockRejectedValue(
+      new Error('Cannot specify both --port and --project-path. Use one or the other.'),
+    );
+
+    await expect(listAvailableTools({ port: '8711', projectPath: '/project' })).rejects.toThrow(
+      'Cannot specify both --port and --project-path. Use one or the other.',
+    );
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, '/project');
+  });
+
+  it('skips busy state checks when an explicit port is provided for sync', async () => {
+    mockResolveUnityPort.mockRejectedValue(new Error('EXPLICIT_PORT_RESOLVED'));
+
+    await expect(syncTools({ port: '8711' })).rejects.toThrow('EXPLICIT_PORT_RESOLVED');
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, undefined);
+  });
+
+  it('preserves usage errors before busy state checks for sync', async () => {
+    mockResolveUnityPort.mockRejectedValue(
+      new Error('Cannot specify both --port and --project-path. Use one or the other.'),
+    );
+
+    await expect(syncTools({ port: '8711', projectPath: '/project' })).rejects.toThrow(
+      'Cannot specify both --port and --project-path. Use one or the other.',
+    );
+
+    expect(mockResolveUnityPort).toHaveBeenCalledWith(8711, '/project');
+  });
+});

package/src/__tests__/cli-project-error.test.ts

@@ -0,0 +1,45 @@
+import { getProjectResolutionErrorLines } from '../cli-project-error.js';
+import { UnityNotRunningError, UnityServerNotRunningError } from '../port-resolver.js';
+import { ProjectMismatchError } from '../project-validator.js';
+
+describe('getProjectResolutionErrorLines', () => {
+  it('returns not-running guidance for UnityNotRunningError', () => {
+    const lines = getProjectResolutionErrorLines(new UnityNotRunningError('/project/root'));
+
+    expect(lines).toEqual([
+      'Error: Unity Editor for this project is not running.',
+      '',
+      '  Project: /project/root',
+      '',
+      'Start the Unity Editor for this project and try again.',
+    ]);
+  });
+
+  it('returns mismatch guidance for ProjectMismatchError', () => {
+    const lines = getProjectResolutionErrorLines(
+      new ProjectMismatchError('/expected/project', '/connected/project'),
+    );
+
+    expect(lines).toEqual([
+      'Error: Connected Unity instance belongs to a different project.',
+      '',
+      '  Project:      /expected/project',
+      '  Connected to: /connected/project',
+      '',
+      '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.',
+    ]);
+  });
+
+  it('returns server-not-running guidance for UnityServerNotRunningError', () => {
+    const lines = getProjectResolutionErrorLines(new UnityServerNotRunningError('/project/root'));
+
+    expect(lines).toEqual([
+      'Error: Unity Editor is running, but Unity CLI Loop server is not.',
+      '',
+      '  Project: /project/root',
+      '',
+      'Start the server from: Window > Unity CLI Loop > Server',
+    ]);
+  });
+});

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

@@ -0,0 +1,129 @@
+type SpawnArgs = [string, string[], Record<string, unknown>?];
+
+const mockSpawn = jest.fn<unknown, SpawnArgs>();
+
+jest.mock('child_process', () => ({
+  spawn: (...args: SpawnArgs): unknown => mockSpawn(...args),
+}));
+
+jest.mock(
+  'launch-unity',
+  () => ({
+    orchestrateLaunch: jest.fn(),
+  }),
+  { virtual: true },
+);
+
+import { getInstalledVersion, updateCli } from '../cli.js';
+
+type CloseHandler = (code: number | null) => void;
+type ErrorHandler = (error: Error) => void;
+type DataHandler = (chunk: Buffer) => void;
+
+interface MockChildProcess {
+  stdout: {
+    on: jest.Mock<void, [string, DataHandler]>;
+  };
+  on: jest.Mock<void, [string, CloseHandler | ErrorHandler]>;
+  emitStdout: (chunk: string) => void;
+  emitClose: (code: number | null) => void;
+  emitError: (error: Error) => void;
+}
+
+function createMockChildProcess(): MockChildProcess {
+  let closeHandler: CloseHandler | undefined;
+  let errorHandler: ErrorHandler | undefined;
+  let dataHandler: DataHandler | undefined;
+
+  return {
+    stdout: {
+      on: jest.fn((event: string, handler: DataHandler) => {
+        if (event === 'data') {
+          dataHandler = handler;
+        }
+      }),
+    },
+    on: jest.fn((event: string, handler: CloseHandler | ErrorHandler) => {
+      if (event === 'close') {
+        closeHandler = handler as CloseHandler;
+      }
+
+      if (event === 'error') {
+        errorHandler = handler as ErrorHandler;
+      }
+    }),
+    emitStdout: (chunk: string): void => {
+      dataHandler?.(Buffer.from(chunk));
+    },
+    emitClose: (code: number | null): void => {
+      closeHandler?.(code);
+    },
+    emitError: (error: Error): void => {
+      errorHandler?.(error);
+    },
+  };
+}
+
+describe('CLI update npm invocation', () => {
+  const expectedNpmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+  beforeEach(() => {
+    mockSpawn.mockReset();
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('gets installed version without enabling shell mode', () => {
+    const child = createMockChildProcess();
+    const callback = jest.fn();
+    mockSpawn.mockReturnValue(child);
+
+    getInstalledVersion(callback);
+
+    expect(mockSpawn).toHaveBeenCalledWith(expectedNpmCommand, [
+      'list',
+      '-g',
+      'uloop-cli',
+      '--json',
+    ]);
+    expect(mockSpawn.mock.calls[0]).toHaveLength(2);
+
+    child.emitStdout(JSON.stringify({ dependencies: { 'uloop-cli': { version: '1.8.0' } } }));
+    child.emitClose(0);
+
+    expect(callback).toHaveBeenCalledWith('1.8.0');
+  });
+
+  it('updates the CLI without enabling shell mode', () => {
+    const updateChild = createMockChildProcess();
+    const listChild = createMockChildProcess();
+    mockSpawn.mockReturnValueOnce(updateChild).mockReturnValueOnce(listChild);
+
+    updateCli();
+
+    expect(mockSpawn).toHaveBeenNthCalledWith(
+      1,
+      expectedNpmCommand,
+      ['install', '-g', 'uloop-cli@latest'],
+      { stdio: 'inherit' },
+    );
+    const installOptions = mockSpawn.mock.calls[0]?.[2];
+    expect(installOptions?.['shell']).toBeUndefined();
+
+    updateChild.emitClose(0);
+
+    expect(mockSpawn).toHaveBeenNthCalledWith(2, expectedNpmCommand, [
+      'list',
+      '-g',
+      'uloop-cli',
+      '--json',
+    ]);
+    expect(mockSpawn.mock.calls[1]).toHaveLength(2);
+
+    listChild.emitStdout(JSON.stringify({ dependencies: { 'uloop-cli': { version: '1.7.1' } } }));
+    listChild.emitClose(0);
+  });
+});

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

@@ -1,5 +1,8 @@
-import { isTransportDisconnectError } from '../execute-tool.js';
-import { UnityNotRunningError } from '../port-resolver.js';
+import {
+  diagnoseRetryableProjectConnectionError,
+  isTransportDisconnectError,
+} from '../execute-tool.js';
+import { UnityNotRunningError, UnityServerNotRunningError } from '../port-resolver.js';
 import { ProjectMismatchError } from '../project-validator.js';
 
 describe('isTransportDisconnectError', () => {
@@ -35,7 +38,69 @@ describe('isTransportDisconnectError', () => {
     expect(isTransportDisconnectError(new UnityNotRunningError('/project'))).toBe(false);
   });
 
+  it('returns false for UnityServerNotRunningError', () => {
+    expect(isTransportDisconnectError(new UnityServerNotRunningError('/project'))).toBe(false);
+  });
+
   it('returns false for ProjectMismatchError', () => {
     expect(isTransportDisconnectError(new ProjectMismatchError('/a', '/b'))).toBe(false);
   });
 });
+
+describe('diagnoseRetryableProjectConnectionError', () => {
+  it('returns UnityNotRunningError when connection fails and Unity is not running', async () => {
+    const error = await diagnoseRetryableProjectConnectionError(
+      new Error('Connection error: connect ECONNREFUSED 127.0.0.1:8711'),
+      '/project',
+      true,
+      {
+        findRunningUnityProcessForProjectFn: jest.fn().mockResolvedValue(null),
+      },
+    );
+
+    expect(error).toBeInstanceOf(UnityNotRunningError);
+  });
+
+  it('returns UnityServerNotRunningError when Unity is running but server is unavailable', async () => {
+    const error = await diagnoseRetryableProjectConnectionError(
+      new Error('UNITY_NO_RESPONSE'),
+      '/project',
+      true,
+      {
+        findRunningUnityProcessForProjectFn: jest.fn().mockResolvedValue({ pid: 1234 }),
+      },
+    );
+
+    expect(error).toBeInstanceOf(UnityServerNotRunningError);
+  });
+
+  it('preserves non-retryable errors', async () => {
+    const originalError = new ProjectMismatchError('/expected', '/actual');
+
+    const error = await diagnoseRetryableProjectConnectionError(originalError, '/project', true, {
+      findRunningUnityProcessForProjectFn: jest.fn(),
+    });
+
+    expect(error).toBe(originalError);
+  });
+
+  it('preserves retryable errors when project diagnosis is disabled', async () => {
+    const originalError = new Error('Connection error: connect ECONNREFUSED 127.0.0.1:8711');
+
+    const error = await diagnoseRetryableProjectConnectionError(originalError, '/project', false, {
+      findRunningUnityProcessForProjectFn: jest.fn(),
+    });
+
+    expect(error).toBe(originalError);
+  });
+
+  it('preserves the original error when OS-level process inspection fails', async () => {
+    const originalError = new Error('Connection error: connect ECONNREFUSED 127.0.0.1:8711');
+
+    const error = await diagnoseRetryableProjectConnectionError(originalError, '/project', true, {
+      findRunningUnityProcessForProjectFn: jest.fn().mockRejectedValue(new Error('ps failed')),
+    });
+
+    expect(error).toBe(originalError);
+  });
+});

package/src/__tests__/package-metadata.test.ts

@@ -0,0 +1,28 @@
+// Test reads the checked-in manifest through a stable relative path during Jest execution.
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+type PackageManifest = {
+  readonly bin?: Record<string, string>;
+};
+
+function loadPackageManifest(): PackageManifest {
+  const packageJsonPath = join(__dirname, '..', '..', 'package.json');
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const packageJsonText = readFileSync(packageJsonPath, 'utf8');
+  return JSON.parse(packageJsonText) as PackageManifest;
+}
+
+describe('package metadata', () => {
+  it('avoids bin target prefixes that npm normalizes during publish', () => {
+    const packageManifest = loadPackageManifest();
+    const binEntries = Object.entries(packageManifest.bin ?? {});
+
+    expect(binEntries.length).toBeGreaterThan(0);
+
+    for (const [, binTarget] of binEntries) {
+      expect(binTarget).not.toMatch(/^(?:\.{1,2}[\\/]|[\\/])/);
+    }
+  });
+});

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

@@ -5,7 +5,6 @@ import {
   resolvePortFromUnitySettings,
   validateProjectPath,
   resolveUnityPort,
-  UnityNotRunningError,
 } from '../port-resolver.js';
 
 describe('resolvePortFromUnitySettings', () => {
@@ -93,15 +92,14 @@ describe('resolveUnityPort with project settings', () => {
     rmSync(tempProjectRoot, { recursive: true });
   });
 
-  it('throws UnityNotRunningError when isServerRunning is false', async () => {
+  it('returns port when isServerRunning is false', async () => {
     writeFileSync(
       join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json'),
       JSON.stringify({ isServerRunning: false, customPort: 8700 }),
     );
 
-    await expect(resolveUnityPort(undefined, tempProjectRoot)).rejects.toThrow(
-      UnityNotRunningError,
-    );
+    const port = await resolveUnityPort(undefined, tempProjectRoot);
+    expect(port).toBe(8700);
   });
 
   it('returns port when isServerRunning is true', async () => {