uloop-cli 0.65.0 → 0.66.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.65.0",
+  "version": "0.66.1",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -34,7 +34,7 @@
   },
   "homepage": "https://github.com/hatayama/uLoopMCP#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   },
   "publishConfig": {
     "access": "public",
@@ -46,20 +46,23 @@
     "semver": "7.7.4"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.2",
+    "@eslint/js": "10.0.1",
     "@types/jest": "30.0.0",
     "@types/node": "25.3.0",
     "@types/semver": "7.7.1",
     "esbuild": "0.27.3",
-    "eslint": "9.39.2",
+    "eslint": "10.0.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-prettier": "5.5.5",
-    "eslint-plugin-security": "3.0.1",
+    "eslint-plugin-security": "4.0.0",
     "jest": "30.2.0",
     "prettier": "3.8.1",
     "ts-jest": "29.4.6",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.56.0"
+  },
+  "overrides": {
+    "minimatch": "10.2.2"
   }
 }

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

@@ -1,4 +1,9 @@
-import { resolvePortFromUnitySettings } from '../port-resolver.js';
+import { tmpdir } from 'os';
+import {
+  resolvePortFromUnitySettings,
+  validateProjectPath,
+  resolveUnityPort,
+} from '../port-resolver.js';
 
 describe('resolvePortFromUnitySettings', () => {
   it('returns serverPort when server is running and serverPort is valid', () => {
@@ -61,3 +66,28 @@ describe('resolvePortFromUnitySettings', () => {
     expect(port).toBeNull();
   });
 });
+
+describe('validateProjectPath', () => {
+  it('throws when path does not exist', () => {
+    expect(() => validateProjectPath('/nonexistent/path/to/project')).toThrow(
+      'Path does not exist: /nonexistent/path/to/project',
+    );
+  });
+
+  it('throws when path is not a Unity project', () => {
+    expect(() => validateProjectPath(tmpdir())).toThrow('Not a Unity project');
+  });
+});
+
+describe('resolveUnityPort', () => {
+  it('throws when both port and projectPath are specified', async () => {
+    await expect(resolveUnityPort(8700, '/some/path')).rejects.toThrow(
+      'Cannot specify both --port and --project-path',
+    );
+  });
+
+  it('returns explicit port when only port is specified', async () => {
+    const port = await resolveUnityPort(8711);
+    expect(port).toBe(8711);
+  });
+});

package/src/cli.ts

@@ -33,6 +33,7 @@ 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';
 
 interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
@@ -73,16 +74,18 @@ program
   .command('list')
   .description('List all available tools from Unity')
   .option('-p, --port <port>', 'Unity TCP port')
+  .option('--project-path <path>', 'Unity project path')
   .action(async (options: CliOptions) => {
-    await runWithErrorHandling(() => listAvailableTools(options));
+    await runWithErrorHandling(() => listAvailableTools(extractGlobalOptions(options)));
   });
 
 program
   .command('sync')
   .description('Sync tool definitions from Unity to local cache')
   .option('-p, --port <port>', 'Unity TCP port')
+  .option('--project-path <path>', 'Unity project path')
   .action(async (options: CliOptions) => {
-    await runWithErrorHandling(() => syncTools(options));
+    await runWithErrorHandling(() => syncTools(extractGlobalOptions(options)));
   });
 
 program
@@ -104,8 +107,12 @@ program
 program
   .command('fix')
   .description('Clean up stale lock files that may prevent CLI from connecting')
-  .action(() => {
-    cleanupLockFiles();
+  .option('--project-path <path>', 'Unity project path')
+  .action(async (options: { projectPath?: string }) => {
+    await runWithErrorHandling(() => {
+      cleanupLockFiles(options.projectPath);
+      return Promise.resolve();
+    });
   });
 
 // Register skills subcommand
@@ -144,6 +151,7 @@ function registerToolCommand(tool: ToolDefinition): void {
 
   // Add global options
   cmd.option('-p, --port <port>', 'Unity TCP port');
+  cmd.option('--project-path <path>', 'Unity project path');
 
   cmd.action(async (options: CliOptions) => {
     const params = buildParams(options, properties);
@@ -294,6 +302,7 @@ function convertValue(value: unknown, propInfo: ToolProperty): unknown {
 function extractGlobalOptions(options: Record<string, unknown>): GlobalOptions {
   return {
     port: options['port'] as string | undefined,
+    projectPath: options['projectPath'] as string | undefined,
   };
 }
 
@@ -592,8 +601,9 @@ const LOCK_FILES = ['compiling.lock', 'domainreload.lock', 'serverstarting.lock'
 /**
  * Clean up stale lock files that may prevent CLI from connecting to Unity.
  */
-function cleanupLockFiles(): void {
-  const projectRoot = findUnityProjectRoot();
+function cleanupLockFiles(projectPath?: string): void {
+  const projectRoot =
+    projectPath !== undefined ? validateProjectPath(projectPath) : findUnityProjectRoot();
   if (projectRoot === null) {
     console.error('Could not find Unity project root.');
     process.exit(1);
@@ -757,22 +767,38 @@ function shouldSkipAutoSync(cmdName: string | undefined, args: string[]): boolea
 }
 
 function extractSyncGlobalOptions(args: string[]): GlobalOptions {
+  const options: GlobalOptions = {};
+
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--port' || arg === '-p') {
       const nextArg = args[i + 1];
       if (nextArg !== undefined && !nextArg.startsWith('-')) {
-        return { port: nextArg };
+        options.port = nextArg;
       }
       continue;
     }
 
     if (arg.startsWith('--port=')) {
-      return { port: arg.slice('--port='.length) };
+      options.port = arg.slice('--port='.length);
+      continue;
+    }
+
+    if (arg === '--project-path') {
+      const nextArg = args[i + 1];
+      if (nextArg !== undefined && !nextArg.startsWith('-')) {
+        options.projectPath = nextArg;
+      }
+      continue;
+    }
+
+    if (arg.startsWith('--project-path=')) {
+      options.projectPath = arg.slice('--project-path='.length);
+      continue;
     }
   }
 
-  return {};
+  return options;
 }
 
 /**

package/src/commands/focus-window.ts

@@ -10,13 +10,31 @@
 import { Command } from 'commander';
 import { findRunningUnityProcess, focusUnityProcess } from 'launch-unity';
 import { findUnityProjectRoot } from '../project-root.js';
+import { validateProjectPath } from '../port-resolver.js';
 
 export function registerFocusWindowCommand(program: Command): void {
   program
     .command('focus-window')
     .description('Bring Unity Editor window to front using OS-level commands')
-    .action(async () => {
-      const projectRoot = findUnityProjectRoot();
+    .option('--project-path <path>', 'Unity project path')
+    .action(async (options: { projectPath?: string }) => {
+      let projectRoot: string | null;
+      if (options.projectPath !== undefined) {
+        try {
+          projectRoot = validateProjectPath(options.projectPath);
+        } catch (error) {
+          console.error(
+            JSON.stringify({
+              Success: false,
+              Message: error instanceof Error ? error.message : String(error),
+            }),
+          );
+          process.exit(1);
+          return;
+        }
+      } else {
+        projectRoot = findUnityProjectRoot();
+      }
       if (projectRoot === null) {
         console.error(
           JSON.stringify({

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.65.0",
+  "version": "0.66.1",
   "tools": [
     {
       "name": "compile",

package/src/execute-tool.ts

@@ -12,7 +12,7 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import * as semver from 'semver';
 import { DirectUnityClient } from './direct-unity-client.js';
-import { resolveUnityPort } from './port-resolver.js';
+import { resolveUnityPort, validateProjectPath } from './port-resolver.js';
 import { saveToolsCache, getCacheFilePath, ToolsCache, ToolDefinition } from './tool-cache.js';
 import { VERSION } from './version.js';
 import { createSpinner } from './spinner.js';
@@ -61,6 +61,7 @@ function suppressStdinEcho(): () => void {
 
 export interface GlobalOptions {
   port?: string;
+  projectPath?: string;
 }
 
 function stripInternalFields(result: Record<string, unknown>): Record<string, unknown> {
@@ -162,8 +163,9 @@ function checkServerVersion(result: Record<string, unknown>): void {
  * Check if Unity is in a busy state (compiling, reloading, or server starting).
  * Throws an error with appropriate message if busy.
  */
-function checkUnityBusyState(): void {
-  const projectRoot = findUnityProjectRoot();
+function checkUnityBusyState(projectPath?: string): void {
+  const projectRoot =
+    projectPath !== undefined ? validateProjectPath(projectPath) : findUnityProjectRoot();
   if (projectRoot === null) {
     return;
   }
@@ -197,7 +199,7 @@ export async function executeToolCommand(
     }
     portNumber = parsed;
   }
-  const port = await resolveUnityPort(portNumber);
+  const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
   const compileOptions = getCompileExecutionOptions(toolName, params);
   const shouldWaitForDomainReload = compileOptions.waitForDomainReload;
   const compileRequestId = shouldWaitForDomainReload ? ensureCompileRequestId(params) : undefined;
@@ -207,7 +209,10 @@ export async function executeToolCommand(
 
   let lastError: unknown;
   let immediateResult: Record<string, unknown> | undefined;
-  const projectRoot = findUnityProjectRoot();
+  const projectRoot =
+    globalOptions.projectPath !== undefined
+      ? validateProjectPath(globalOptions.projectPath)
+      : findUnityProjectRoot();
 
   // Monotonically-increasing flag: once true, retries cannot reset it to false.
   // The retry loop overwrites `lastError` and `immediateResult` on each attempt,
@@ -218,7 +223,7 @@ export async function executeToolCommand(
   let requestDispatched = false;
 
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState();
+    checkUnityBusyState(globalOptions.projectPath);
 
     const client = new DirectUnityClient(port);
     try {
@@ -377,14 +382,14 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
     }
     portNumber = parsed;
   }
-  const port = await resolveUnityPort(portNumber);
+  const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
 
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner('Connecting to Unity...');
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState();
+    checkUnityBusyState(globalOptions.projectPath);
 
     const client = new DirectUnityClient(port);
     try {
@@ -465,14 +470,14 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
     }
     portNumber = parsed;
   }
-  const port = await resolveUnityPort(portNumber);
+  const port = await resolveUnityPort(portNumber, globalOptions.projectPath);
 
   const restoreStdin = suppressStdinEcho();
   const spinner = createSpinner('Connecting to Unity...');
 
   let lastError: unknown;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    checkUnityBusyState();
+    checkUnityBusyState(globalOptions.projectPath);
 
     const client = new DirectUnityClient(port);
     try {

package/src/port-resolver.ts

@@ -8,8 +8,8 @@
 
 import { readFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { join } from 'path';
-import { findUnityProjectRoot } from './project-root.js';
+import { join, resolve } from 'path';
+import { findUnityProjectRoot, isUnityProject, hasUloopInstalled } from './project-root.js';
 
 const DEFAULT_PORT = 8700;
 
@@ -54,14 +54,52 @@ export function resolvePortFromUnitySettings(settings: UnityMcpSettings): number
   return null;
 }
 
-export async function resolveUnityPort(explicitPort?: number): Promise<number> {
+export function validateProjectPath(projectPath: string): string {
+  const resolved = resolve(projectPath);
+
+  if (!existsSync(resolved)) {
+    throw new Error(`Path does not exist: ${resolved}`);
+  }
+
+  if (!isUnityProject(resolved)) {
+    throw new Error(`Not a Unity project (Assets/ or ProjectSettings/ not found): ${resolved}`);
+  }
+
+  if (!hasUloopInstalled(resolved)) {
+    throw new Error(
+      `uLoopMCP is not installed in this project (UserSettings/UnityMcpSettings.json not found): ${resolved}`,
+    );
+  }
+
+  return resolved;
+}
+
+export async function resolveUnityPort(
+  explicitPort?: number,
+  projectPath?: string,
+): Promise<number> {
+  if (explicitPort !== undefined && projectPath !== undefined) {
+    throw new Error('Cannot specify both --port and --project-path. Use one or the other.');
+  }
+
   if (explicitPort !== undefined) {
     return explicitPort;
   }
 
+  if (projectPath !== undefined) {
+    const resolved = validateProjectPath(projectPath);
+    const settingsPort = await readPortFromSettings(resolved);
+    if (settingsPort !== null) {
+      return settingsPort;
+    }
+    return DEFAULT_PORT;
+  }
+
   const projectRoot = findUnityProjectRoot();
   if (projectRoot === null) {
-    throw new Error('Unity project not found. Use --port option to specify the port explicitly.');
+    throw new Error(
+      'Unity project not found. Use --port or --project-path option to specify the target.',
+    );
   }
 
   const settingsPort = await readPortFromSettings(projectRoot);

package/src/project-root.ts

@@ -22,13 +22,13 @@ const EXCLUDED_DIRS = new Set([
   'Library',
 ]);
 
-function isUnityProject(dirPath: string): boolean {
+export function isUnityProject(dirPath: string): boolean {
   const hasAssets = existsSync(join(dirPath, 'Assets'));
   const hasProjectSettings = existsSync(join(dirPath, 'ProjectSettings'));
   return hasAssets && hasProjectSettings;
 }
 
-function hasUloopInstalled(dirPath: string): boolean {
+export function hasUloopInstalled(dirPath: string): boolean {
   return existsSync(join(dirPath, 'UserSettings/UnityMcpSettings.json'));
 }
 

package/src/skills/skill-definitions/cli-only/uloop-focus-window/SKILL.md

@@ -17,6 +17,13 @@ uloop focus-window
 
 None.
 
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--project-path <path>` | Target a specific Unity project (mutually exclusive with `--port`). Path resolution follows the same rules as `cd` — absolute paths are used as-is, relative paths are resolved from cwd. |
+| `-p, --port <port>` | Specify Unity TCP port directly (mutually exclusive with `--project-path`). |
+
 ## Examples
 
 ```bash

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