uloop-cli 1.7.0 → 1.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via Unity CLI Loop",
   "main": "dist/cli.bundle.cjs",
@@ -57,11 +57,11 @@
     "eslint-plugin-prettier": "5.5.5",
     "eslint-plugin-security": "4.0.0",
     "jest": "30.3.0",
-    "knip": "6.3.0",
+    "knip": "6.3.1",
     "prettier": "3.8.1",
     "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,33 @@
+import { getProjectResolutionErrorLines } from '../cli-project-error.js';
+import { UnityNotRunningError } 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.',
+    ]);
+  });
+});

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/cli-project-error.ts

@@ -0,0 +1,26 @@
+import { UnityNotRunningError } from './port-resolver.js';
+import { ProjectMismatchError } from './project-validator.js';
+
+export function getProjectResolutionErrorLines(
+  error: UnityNotRunningError | ProjectMismatchError,
+): string[] {
+  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

@@ -39,6 +39,7 @@ import { findUnityProjectRoot } from './project-root.js';
 import { validateProjectPath, UnityNotRunningError } 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;
@@ -430,24 +431,16 @@ async function runWithErrorHandling(fn: () => Promise<void>): Promise<void> {
     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.');
+      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 +597,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 +654,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 +1029,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.2",
   "tools": [
     {
       "name": "compile",

package/src/execute-tool.ts

@@ -188,6 +188,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 +209,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 +237,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 {
@@ -391,6 +400,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 +413,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 {
@@ -488,6 +498,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 +511,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 {

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 {

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