uloop-cli 0.68.2 → 0.69.0

package/knip.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "project": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.68.2",
+  "version": "0.69.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -14,6 +14,7 @@
     "lint:fix": "eslint src --fix",
     "format": "prettier --write src/**/*.ts",
     "format:check": "prettier --check src/**/*.ts",
+    "knip": "knip",
     "test:cli": "jest src/__tests__ --testTimeout=60000 --runInBand"
   },
   "keywords": [
@@ -48,7 +49,7 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/jest": "30.0.0",
-    "@types/node": "25.3.2",
+    "@types/node": "25.3.3",
     "@types/semver": "7.7.1",
     "esbuild": "0.27.3",
     "eslint": "10.0.2",
@@ -56,9 +57,9 @@
     "eslint-plugin-prettier": "5.5.5",
     "eslint-plugin-security": "4.0.0",
     "jest": "30.2.0",
+    "knip": "5.85.0",
     "prettier": "3.8.1",
     "ts-jest": "29.4.6",
-    "tsx": "4.21.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.56.1"
   },

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

@@ -460,16 +460,16 @@ describe('CLI E2E Tests (requires running Unity)', () => {
     });
   });
 
-  describe('get-provider-details', () => {
+  describe('get-unity-search-providers', () => {
     it('should retrieve search providers', () => {
-      const result = runCliJson<{ Providers: unknown[] }>('get-provider-details');
+      const result = runCliJson<{ Providers: unknown[] }>('get-unity-search-providers');
 
       expect(Array.isArray(result.Providers)).toBe(true);
     });
 
     it('should support --include-descriptions false to exclude descriptions', () => {
       const result = runCliJson<{ Providers: unknown[] }>(
-        'get-provider-details --include-descriptions false',
+        'get-unity-search-providers --include-descriptions false',
       );
 
       expect(Array.isArray(result.Providers)).toBe(true);
@@ -477,7 +477,7 @@ describe('CLI E2E Tests (requires running Unity)', () => {
 
     it('should support --sort-by-priority false to disable priority sorting', () => {
       const result = runCliJson<{ Providers: unknown[] }>(
-        'get-provider-details --sort-by-priority false',
+        'get-unity-search-providers --sort-by-priority false',
       );
 
       expect(Array.isArray(result.Providers)).toBe(true);
@@ -501,6 +501,48 @@ describe('CLI E2E Tests (requires running Unity)', () => {
       expect(stdout).toContain('--force-recompile');
     });
 
+    it('should display grouped help with category headings', () => {
+      const { stdout, exitCode } = runCli('--help');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Built-in Tools:');
+      expect(stdout).toContain('CLI Commands:');
+      // CLI Commands should appear before Built-in Tools
+      const cliIndex: number = stdout.indexOf('CLI Commands:');
+      const builtInIndex: number = stdout.indexOf('Built-in Tools:');
+      expect(cliIndex).toBeLessThan(builtInIndex);
+    });
+
+    it('should display Third-party Tools section when cache contains third-party tools', () => {
+      const { stdout, exitCode } = runCli('--help');
+
+      expect(exitCode).toBe(0);
+      // hello-world is a third-party tool present in the local cache but not in default-tools.json
+      if (stdout.includes('hello-world')) {
+        expect(stdout).toContain('Third-party Tools:');
+        const builtInIndex: number = stdout.indexOf('Built-in Tools:');
+        const thirdPartyIndex: number = stdout.indexOf('Third-party Tools:');
+        expect(builtInIndex).toBeLessThan(thirdPartyIndex);
+      }
+    });
+
+    it('should resolve tool cache via --project-path', () => {
+      const withProjectPath = runCli(`--help --project-path "${UNITY_PROJECT_ROOT}"`);
+      const withoutProjectPath = runCli('--help');
+
+      expect(withProjectPath.exitCode).toBe(0);
+      expect(withoutProjectPath.exitCode).toBe(0);
+
+      // Both should show the same category headings
+      expect(withProjectPath.stdout).toContain('Built-in Tools:');
+      expect(withProjectPath.stdout).toContain('CLI Commands:');
+
+      // Third-party tools visible in normal help should also appear with --project-path
+      if (withoutProjectPath.stdout.includes('Third-party Tools:')) {
+        expect(withProjectPath.stdout).toContain('Third-party Tools:');
+      }
+    });
+
     it('should display boolean options with value format in get-hierarchy help', () => {
       const { stdout, exitCode } = runCli('get-hierarchy --help');
 

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

@@ -1,4 +1,6 @@
 import { isTransportDisconnectError } from '../execute-tool.js';
+import { UnityNotRunningError } from '../port-resolver.js';
+import { ProjectMismatchError } from '../project-validator.js';
 
 describe('isTransportDisconnectError', () => {
   it('returns true for UNITY_NO_RESPONSE', () => {
@@ -28,4 +30,12 @@ describe('isTransportDisconnectError', () => {
     expect(isTransportDisconnectError(null)).toBe(false);
     expect(isTransportDisconnectError(undefined)).toBe(false);
   });
+
+  it('returns false for UnityNotRunningError', () => {
+    expect(isTransportDisconnectError(new UnityNotRunningError('/project'))).toBe(false);
+  });
+
+  it('returns false for ProjectMismatchError', () => {
+    expect(isTransportDisconnectError(new ProjectMismatchError('/a', '/b'))).toBe(false);
+  });
 });

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

@@ -1,8 +1,11 @@
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
 import { tmpdir } from 'os';
 import {
   resolvePortFromUnitySettings,
   validateProjectPath,
   resolveUnityPort,
+  UnityNotRunningError,
 } from '../port-resolver.js';
 
 describe('resolvePortFromUnitySettings', () => {
@@ -75,3 +78,68 @@ describe('resolveUnityPort', () => {
     expect(port).toBe(8711);
   });
 });
+
+describe('resolveUnityPort with project settings', () => {
+  let tempProjectRoot: string;
+
+  beforeEach(() => {
+    tempProjectRoot = mkdtempSync(join(tmpdir(), 'unity-port-test-'));
+    mkdirSync(join(tempProjectRoot, 'Assets'));
+    mkdirSync(join(tempProjectRoot, 'ProjectSettings'));
+    mkdirSync(join(tempProjectRoot, 'UserSettings'));
+  });
+
+  afterEach(() => {
+    rmSync(tempProjectRoot, { recursive: true });
+  });
+
+  it('throws UnityNotRunningError 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,
+    );
+  });
+
+  it('returns port when isServerRunning is true', async () => {
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json'),
+      JSON.stringify({ isServerRunning: true, customPort: 8711 }),
+    );
+
+    const port = await resolveUnityPort(undefined, tempProjectRoot);
+    expect(port).toBe(8711);
+  });
+
+  it('returns port when isServerRunning is undefined (old settings format)', async () => {
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json'),
+      JSON.stringify({ customPort: 8711 }),
+    );
+
+    const port = await resolveUnityPort(undefined, tempProjectRoot);
+    expect(port).toBe(8711);
+  });
+
+  it('throws when settings file has no valid port', async () => {
+    writeFileSync(
+      join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json'),
+      JSON.stringify({ isServerRunning: true }),
+    );
+
+    await expect(resolveUnityPort(undefined, tempProjectRoot)).rejects.toThrow(
+      'Could not read Unity server port from settings',
+    );
+  });
+
+  it('throws when settings file contains invalid JSON', async () => {
+    writeFileSync(join(tempProjectRoot, 'UserSettings/UnityMcpSettings.json'), 'not valid json{{{');
+
+    await expect(resolveUnityPort(undefined, tempProjectRoot)).rejects.toThrow(
+      'Could not read Unity server port from settings',
+    );
+  });
+});

package/src/__tests__/project-validator.test.ts

@@ -0,0 +1,107 @@
+import { mkdtempSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { ProjectMismatchError, validateConnectedProject } from '../project-validator.js';
+import { isTransportDisconnectError } from '../execute-tool.js';
+import type { DirectUnityClient } from '../direct-unity-client.js';
+
+function createMockClient(response?: unknown, error?: Error): DirectUnityClient {
+  return {
+    isConnected: () => true,
+    sendRequest: jest.fn().mockImplementation(() => {
+      if (error) {
+        return Promise.reject(error);
+      }
+      return Promise.resolve(response);
+    }),
+    connect: jest.fn(),
+    disconnect: jest.fn(),
+  } as unknown as DirectUnityClient;
+}
+
+describe('validateConnectedProject', () => {
+  let tempDirA: string;
+  let tempDirB: string;
+
+  beforeEach(() => {
+    tempDirA = mkdtempSync(join(tmpdir(), 'project-a-'));
+    tempDirB = mkdtempSync(join(tmpdir(), 'project-b-'));
+    mkdirSync(join(tempDirA, 'Assets'));
+    mkdirSync(join(tempDirB, 'Assets'));
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    rmSync(tempDirA, { recursive: true });
+    rmSync(tempDirB, { recursive: true });
+  });
+
+  it('throws ProjectMismatchError when connected project differs from expected', async () => {
+    const client = createMockClient({ DataPath: join(tempDirB, 'Assets') });
+
+    await expect(validateConnectedProject(client, tempDirA)).rejects.toThrow(ProjectMismatchError);
+  });
+
+  it('does not throw when connected project matches expected', async () => {
+    const client = createMockClient({ DataPath: join(tempDirA, 'Assets') });
+
+    await expect(validateConnectedProject(client, tempDirA)).resolves.toBeUndefined();
+  });
+
+  it('normalizes paths with trailing separators', async () => {
+    const client = createMockClient({ DataPath: join(tempDirA, 'Assets') });
+
+    await expect(validateConnectedProject(client, tempDirA + '/')).resolves.toBeUndefined();
+  });
+
+  it('logs warning and continues when get-version returns Method not found', async () => {
+    const client = createMockClient(undefined, new Error('Unity error: Method not found (-32601)'));
+    const stderrSpy = jest.spyOn(console, 'error').mockImplementation();
+
+    await expect(validateConnectedProject(client, tempDirA)).resolves.toBeUndefined();
+
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Could not verify project identity'),
+    );
+  });
+
+  it('re-throws non-Method-not-found errors', async () => {
+    const client = createMockClient(undefined, new Error('Unity error: some other error'));
+
+    await expect(validateConnectedProject(client, tempDirA)).rejects.toThrow(
+      'Unity error: some other error',
+    );
+  });
+
+  it('logs warning and continues when DataPath is missing from response', async () => {
+    const client = createMockClient({});
+    const stderrSpy = jest.spyOn(console, 'error').mockImplementation();
+
+    await expect(validateConnectedProject(client, tempDirA)).resolves.toBeUndefined();
+
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('invalid get-version response'));
+  });
+
+  it('logs warning and continues when DataPath is empty string', async () => {
+    const client = createMockClient({ DataPath: '' });
+    const stderrSpy = jest.spyOn(console, 'error').mockImplementation();
+
+    await expect(validateConnectedProject(client, tempDirA)).resolves.toBeUndefined();
+
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('invalid get-version response'));
+  });
+});
+
+describe('ProjectMismatchError', () => {
+  it('is not a transport disconnect error', () => {
+    const error = new ProjectMismatchError('/project/a', '/project/b');
+    expect(isTransportDisconnectError(error)).toBe(false);
+  });
+
+  it('stores expected and connected project roots', () => {
+    const error = new ProjectMismatchError('/expected/path', '/connected/path');
+    expect(error.expectedProjectRoot).toBe('/expected/path');
+    expect(error.connectedProjectRoot).toBe('/connected/path');
+    expect(error.message).toBe('PROJECT_MISMATCH');
+  });
+});

package/src/arg-parser.ts

@@ -3,31 +3,6 @@
  * Converts CLI options to Unity tool parameters.
  */
 
-// Object keys come from tool schema definitions which are internal trusted data
-/* eslint-disable security/detect-object-injection */
-
-export interface ToolParameter {
-  Type: string;
-  Description: string;
-  DefaultValue?: unknown;
-  Enum?: string[];
-}
-
-export interface ToolSchema {
-  properties: Record<string, ToolParameter>;
-}
-
-/**
- * Converts kebab-case CLI option name to PascalCase parameter name.
- * e.g., "force-recompile" -> "ForceRecompile"
- */
-export function kebabToPascalCase(kebab: string): string {
-  return kebab
-    .split('-')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join('');
-}
-
 /**
  * Converts PascalCase parameter name to kebab-case CLI option name.
  * e.g., "ForceRecompile" -> "force-recompile"
@@ -36,96 +11,3 @@ export function pascalToKebabCase(pascal: string): string {
   const kebab = pascal.replace(/([A-Z])/g, '-$1').toLowerCase();
   return kebab.startsWith('-') ? kebab.slice(1) : kebab;
 }
-
-/**
- * Parses CLI arguments into tool parameters based on the tool schema.
- */
-export function parseToolArgs(
-  args: string[],
-  schema: ToolSchema,
-  cliOptions: Record<string, unknown>,
-): Record<string, unknown> {
-  const params: Record<string, unknown> = {};
-
-  for (const [paramName, paramInfo] of Object.entries(schema.properties)) {
-    const kebabName = pascalToKebabCase(paramName);
-    const cliValue = cliOptions[kebabName];
-
-    if (cliValue === undefined) {
-      if (paramInfo.DefaultValue !== undefined) {
-        params[paramName] = paramInfo.DefaultValue;
-      }
-      continue;
-    }
-
-    params[paramName] = convertValue(cliValue, paramInfo.Type);
-  }
-
-  return params;
-}
-
-function convertValue(value: unknown, type: string): unknown {
-  if (value === undefined || value === null) {
-    return value;
-  }
-
-  const lowerType = type.toLowerCase();
-
-  switch (lowerType) {
-    case 'boolean':
-      if (typeof value === 'boolean') {
-        return value;
-      }
-      if (typeof value === 'string') {
-        return value.toLowerCase() === 'true';
-      }
-      return Boolean(value);
-
-    case 'number':
-    case 'integer':
-      if (typeof value === 'number') {
-        return value;
-      }
-      if (typeof value === 'string') {
-        const parsed = parseFloat(value);
-        return isNaN(parsed) ? 0 : parsed;
-      }
-      return Number(value);
-
-    case 'string':
-      if (typeof value === 'string') {
-        return value;
-      }
-      if (typeof value === 'number' || typeof value === 'boolean') {
-        return String(value);
-      }
-      return JSON.stringify(value);
-
-    case 'array':
-      if (Array.isArray(value)) {
-        return value;
-      }
-      if (typeof value === 'string') {
-        return value.split(',').map((s) => s.trim());
-      }
-      return [value];
-
-    default:
-      return value;
-  }
-}
-
-/**
- * Generates commander.js option string from parameter info.
- * e.g., "--force-recompile" for boolean, "--max-count <value>" for others
- */
-export function generateOptionString(paramName: string, paramInfo: ToolParameter): string {
-  const kebabName = pascalToKebabCase(paramName);
-  const lowerType = paramInfo.Type.toLowerCase();
-
-  if (lowerType === 'boolean') {
-    return `--${kebabName}`;
-  }
-
-  return `--${kebabName} <value>`;
-}