uloop-cli 0.68.3 → 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.3",
+  "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__/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>`;
-}

package/src/cli.ts

@@ -35,7 +35,8 @@ 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 } from './port-resolver.js';
+import { validateProjectPath, UnityNotRunningError } from './port-resolver.js';
+import { ProjectMismatchError } from './project-validator.js';
 import { filterEnabledTools, isToolEnabled } from './tool-settings-loader.js';
 
 interface CliOptions extends GlobalOptions {
@@ -422,6 +423,28 @@ 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.');
+      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 --port to specify the target.',
+      );
+      process.exit(1);
+    }
+
     const message = error instanceof Error ? error.message : String(error);
 
     // Unity busy states have clear causes - no version diagnostic needed

package/src/compile-helpers.ts

@@ -17,14 +17,14 @@ import { join } from 'path';
 // Only alphanumeric, underscore, and hyphen — blocks path separators and traversal sequences
 const SAFE_REQUEST_ID_PATTERN: RegExp = /^[a-zA-Z0-9_-]+$/;
 
-export const COMPILE_FORCE_RECOMPILE_ARG_KEYS = [
+const COMPILE_FORCE_RECOMPILE_ARG_KEYS = [
   'ForceRecompile',
   'forceRecompile',
   'force_recompile',
   'force-recompile',
 ] as const;
 
-export const COMPILE_WAIT_FOR_DOMAIN_RELOAD_ARG_KEYS = [
+const COMPILE_WAIT_FOR_DOMAIN_RELOAD_ARG_KEYS = [
   'WaitForDomainReload',
   'waitForDomainReload',
   'wait_for_domain_reload',
@@ -36,7 +36,7 @@ export interface CompileExecutionOptions {
   waitForDomainReload: boolean;
 }
 
-export interface CompileCompletionWaitOptions {
+interface CompileCompletionWaitOptions {
   projectRoot: string;
   requestId: string;
   timeoutMs: number;
@@ -45,9 +45,9 @@ export interface CompileCompletionWaitOptions {
   isUnityReadyWhenIdle?: () => Promise<boolean>;
 }
 
-export type CompileCompletionOutcome = 'completed' | 'timed_out';
+type CompileCompletionOutcome = 'completed' | 'timed_out';
 
-export interface CompileCompletionResult<T> {
+interface CompileCompletionResult<T> {
   outcome: CompileCompletionOutcome;
   result?: T;
 }

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.68.3",
+  "version": "0.69.0",
   "tools": [
     {
       "name": "compile",

package/src/direct-unity-client.ts

@@ -13,14 +13,14 @@ const JSONRPC_VERSION = '2.0';
 const DEFAULT_HOST = '127.0.0.1';
 const NETWORK_TIMEOUT_MS = 180000;
 
-export interface JsonRpcRequest {
+interface JsonRpcRequest {
   jsonrpc: string;
   method: string;
   params?: Record<string, unknown>;
   id: number;
 }
 
-export interface JsonRpcResponse {
+interface JsonRpcResponse {
   jsonrpc: string;
   result?: unknown;
   error?: {

package/src/execute-tool.ts

@@ -13,6 +13,7 @@ import { join } from 'path';
 import * as semver from 'semver';
 import { DirectUnityClient } from './direct-unity-client.js';
 import { resolveUnityPort, 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';
@@ -214,6 +215,9 @@ export async function executeToolCommand(
       ? validateProjectPath(globalOptions.projectPath)
       : findUnityProjectRoot();
 
+  // Validate project identity only when port was auto-resolved (not --port) and project root is known
+  const shouldValidateProject = portNumber === undefined && projectRoot !== null;
+
   // 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
@@ -229,6 +233,10 @@ export async function executeToolCommand(
     try {
       await client.connect();
 
+      if (shouldValidateProject) {
+        await validateConnectedProject(client, projectRoot);
+      }
+
       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
@@ -383,6 +391,11 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
     portNumber = parsed;
   }
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
+  const projectRoot =
+    globalOptions.projectPath !== undefined
+      ? validateProjectPath(globalOptions.projectPath)
+      : findUnityProjectRoot();
+  const shouldValidateProject = portNumber === undefined && projectRoot !== null;
 
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner('Connecting to Unity...');
@@ -395,6 +408,10 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
     try {
       await client.connect();
 
+      if (shouldValidateProject) {
+        await validateConnectedProject(client, projectRoot);
+      }
+
       spinner.update('Fetching tool list...');
       const result = await client.sendRequest<{
         Tools: Array<{ name: string; description: string }>;
@@ -471,6 +488,11 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
     portNumber = parsed;
   }
   const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
+  const projectRoot =
+    globalOptions.projectPath !== undefined
+      ? validateProjectPath(globalOptions.projectPath)
+      : findUnityProjectRoot();
+  const shouldValidateProject = portNumber === undefined && projectRoot !== null;
 
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner('Connecting to Unity...');
@@ -483,6 +505,10 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
     try {
       await client.connect();
 
+      if (shouldValidateProject) {
+        await validateConnectedProject(client, projectRoot);
+      }
+
       spinner.update('Syncing tools...');
       const result = await client.sendRequest<{
         Tools: UnityToolInfo[];

package/src/port-resolver.ts

@@ -11,7 +11,11 @@ import { existsSync } from 'fs';
 import { join, resolve } from 'path';
 import { findUnityProjectRoot, isUnityProject, hasUloopInstalled } from './project-root.js';
 
-const DEFAULT_PORT = 8700;
+export class UnityNotRunningError extends Error {
+  constructor(public readonly projectRoot: string) {
+    super('UNITY_NOT_RUNNING');
+  }
+}
 
 interface UnityMcpSettings {
   isServerRunning?: boolean;
@@ -78,11 +82,7 @@ export async function resolveUnityPort(
 
   if (projectPath !== undefined) {
     const resolved = validateProjectPath(projectPath);
-    const settingsPort = await readPortFromSettings(resolved);
-    if (settingsPort !== null) {
-      return settingsPort;
-    }
-    return DEFAULT_PORT;
+    return await readPortFromSettingsOrThrow(resolved);
   }
 
   const projectRoot = findUnityProjectRoot();
@@ -92,34 +92,55 @@ export async function resolveUnityPort(
     );
   }
 
-  const settingsPort = await readPortFromSettings(projectRoot);
-  if (settingsPort !== null) {
-    return settingsPort;
-  }
+  return await readPortFromSettingsOrThrow(projectRoot);
+}
 
-  return DEFAULT_PORT;
+function createSettingsReadError(projectRoot: string): Error {
+  const settingsPath = join(projectRoot, 'UserSettings/UnityMcpSettings.json');
+  return new Error(
+    `Could not read Unity server port from settings.\n\n` +
+      `  Settings file: ${settingsPath}\n\n` +
+      `Run 'uloop launch -r' to restart Unity, or use --port to specify the port directly.`,
+  );
 }
 
-async function readPortFromSettings(projectRoot: string): Promise<number | null> {
+// File I/O and JSON parsing can fail for external reasons (permissions, corruption, concurrent writes)
+async function readPortFromSettingsOrThrow(projectRoot: string): Promise<number> {
   const settingsPath = join(projectRoot, 'UserSettings/UnityMcpSettings.json');
 
   if (!existsSync(settingsPath)) {
-    return null;
+    throw createSettingsReadError(projectRoot);
   }
 
   let content: string;
   try {
     content = await readFile(settingsPath, 'utf-8');
   } catch {
-    return null;
+    throw createSettingsReadError(projectRoot);
   }
 
-  let settings: UnityMcpSettings;
+  let parsed: unknown;
   try {
-    settings = JSON.parse(content) as UnityMcpSettings;
+    parsed = JSON.parse(content);
   } catch {
-    return null;
+    throw createSettingsReadError(projectRoot);
   }
 
-  return resolvePortFromUnitySettings(settings);
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw createSettingsReadError(projectRoot);
+  }
+  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) {
+    throw createSettingsReadError(projectRoot);
+  }
+
+  return port;
 }

package/src/project-root.ts

@@ -143,7 +143,7 @@ export function findUnityProjectRoot(startPath: string = process.cwd()): string
   return findUnityProjectInParents(startPath);
 }
 
-export interface UnityProjectStatus {
+interface UnityProjectStatus {
   found: boolean;
   path: string | null;
   hasUloop: boolean;