uloop-cli 0.66.1 → 0.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.66.1",
+  "version": "0.67.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -51,7 +51,7 @@
     "@types/node": "25.3.0",
     "@types/semver": "7.7.1",
     "esbuild": "0.27.3",
-    "eslint": "10.0.1",
+    "eslint": "10.0.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-prettier": "5.5.5",
     "eslint-plugin-security": "4.0.0",
@@ -60,7 +60,7 @@
     "ts-jest": "29.4.6",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.56.0"
+    "typescript-eslint": "8.56.1"
   },
   "overrides": {
     "minimatch": "10.2.2"

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

@@ -6,51 +6,36 @@ import {
 } from '../port-resolver.js';
 
 describe('resolvePortFromUnitySettings', () => {
-  it('returns serverPort when server is running and serverPort is valid', () => {
+  it('returns customPort when valid', () => {
     const port = resolvePortFromUnitySettings({
       isServerRunning: true,
-      serverPort: 8711,
-      customPort: 8700,
-    });
-
-    expect(port).toBe(8711);
-  });
-
-  it('returns customPort when server is not running', () => {
-    const port = resolvePortFromUnitySettings({
-      isServerRunning: false,
-      serverPort: 8711,
       customPort: 8700,
     });
 
     expect(port).toBe(8700);
   });
 
-  it('returns customPort when serverPort is invalid', () => {
+  it('returns customPort regardless of isServerRunning flag', () => {
     const port = resolvePortFromUnitySettings({
       isServerRunning: false,
-      serverPort: 0,
       customPort: 8711,
     });
 
     expect(port).toBe(8711);
   });
 
-  it('falls back to serverPort when customPort is invalid', () => {
+  it('returns null when customPort is invalid', () => {
     const port = resolvePortFromUnitySettings({
-      isServerRunning: false,
-      serverPort: 8711,
+      isServerRunning: true,
       customPort: 0,
     });
 
-    expect(port).toBe(8711);
+    expect(port).toBeNull();
   });
 
-  it('returns null when both ports are invalid', () => {
+  it('returns null when customPort is missing', () => {
     const port = resolvePortFromUnitySettings({
-      isServerRunning: false,
-      serverPort: 0,
-      customPort: 0,
+      isServerRunning: true,
     });
 
     expect(port).toBeNull();
@@ -59,7 +44,6 @@ describe('resolvePortFromUnitySettings', () => {
   it('returns null when port is not an integer', () => {
     const port = resolvePortFromUnitySettings({
       isServerRunning: true,
-      serverPort: 8711.5,
       customPort: 8700.1,
     });
 

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

@@ -0,0 +1,97 @@
+// Test helpers use dynamic paths for temp directories and console assertions
+/* eslint-disable security/detect-non-literal-fs-filename, no-console */
+
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { findUnityProjectRoot, resetMultipleProjectsWarning } from '../project-root.js';
+
+function createUnityProject(basePath: string, name: string): string {
+  const projectPath = join(basePath, name);
+  mkdirSync(join(projectPath, 'Assets'), { recursive: true });
+  mkdirSync(join(projectPath, 'ProjectSettings'), { recursive: true });
+  mkdirSync(join(projectPath, 'UserSettings'), { recursive: true });
+  writeFileSync(join(projectPath, 'UserSettings/UnityMcpSettings.json'), '{}');
+  return projectPath;
+}
+
+describe('findUnityProjectRoot', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    resetMultipleProjectsWarning();
+    testDir = join(tmpdir(), `uloop-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('returns null when no Unity project is found', () => {
+    const result = findUnityProjectRoot(testDir);
+
+    expect(result).toBeNull();
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it('returns project path without warning when single project found', () => {
+    const projectPath = createUnityProject(testDir, 'MyProject');
+
+    const result = findUnityProjectRoot(testDir);
+
+    expect(result).toBe(projectPath);
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it('warns once when multiple projects found', () => {
+    createUnityProject(testDir, 'ProjectA');
+    createUnityProject(testDir, 'ProjectB');
+
+    findUnityProjectRoot(testDir);
+
+    expect(console.error).toHaveBeenCalled();
+    const calls = (console.error as jest.Mock).mock.calls.map((c: unknown[]) => c[0] as string);
+    const warningLine = calls.find((msg: string) => msg.includes('Multiple Unity projects'));
+    expect(warningLine).toBeDefined();
+    const actionLine = calls.find((msg: string) => msg.includes('--project-path'));
+    expect(actionLine).toBeDefined();
+  });
+
+  it('does not warn on second call (once-per-process)', () => {
+    createUnityProject(testDir, 'ProjectA');
+    createUnityProject(testDir, 'ProjectB');
+
+    findUnityProjectRoot(testDir);
+    (console.error as jest.Mock).mockClear();
+
+    findUnityProjectRoot(testDir);
+
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it('warns again after resetMultipleProjectsWarning()', () => {
+    createUnityProject(testDir, 'ProjectA');
+    createUnityProject(testDir, 'ProjectB');
+
+    findUnityProjectRoot(testDir);
+    (console.error as jest.Mock).mockClear();
+
+    resetMultipleProjectsWarning();
+    findUnityProjectRoot(testDir);
+
+    expect(console.error).toHaveBeenCalled();
+    const calls = (console.error as jest.Mock).mock.calls.map((c: unknown[]) => c[0] as string);
+    const warningLine = calls.find((msg: string) => msg.includes('Multiple Unity projects'));
+    expect(warningLine).toBeDefined();
+  });
+
+  it('returns first project alphabetically when multiple found', () => {
+    createUnityProject(testDir, 'Zebra');
+    createUnityProject(testDir, 'Alpha');
+
+    const result = findUnityProjectRoot(testDir);
+
+    expect(result).toBe(join(testDir, 'Alpha'));
+  });
+});

package/src/cli.ts

@@ -23,6 +23,7 @@ import {
 import {
   loadToolsCache,
   hasCacheFile,
+  getDefaultTools,
   ToolDefinition,
   ToolProperty,
   getCachedServerVersion,
@@ -61,7 +62,8 @@ const program = new Command();
 program
   .name('uloop')
   .description('Unity MCP CLI - Direct communication with Unity Editor')
-  .version(VERSION, '-v, --version', 'Output the version number');
+  .version(VERSION, '-v, --version', 'Output the version number')
+  .showHelpAfterError('(run with -h for available options)');
 
 // --list-commands: Output command names for shell completion
 program.option('--list-commands', 'List all command names (for shell completion)');
@@ -813,6 +815,20 @@ async function main(): Promise<void> {
   const cmdName = args.find((arg) => !arg.startsWith('-'));
   const syncGlobalOptions = extractSyncGlobalOptions(args);
 
+  // No command name = no Unity operation; skip project detection
+  const NO_PROJECT_COMMANDS = [UPDATE_COMMAND, 'completion'] as const;
+  const skipProjectDetection =
+    cmdName === undefined || (NO_PROJECT_COMMANDS as readonly string[]).includes(cmdName);
+
+  if (skipProjectDetection) {
+    const defaultTools = getDefaultTools();
+    for (const tool of defaultTools.tools) {
+      registerToolCommand(tool);
+    }
+    program.parse();
+    return;
+  }
+
   if (!shouldSkipAutoSync(cmdName, args)) {
     // Check if cache version is outdated and auto-sync if needed
     const cachedVersion = loadToolsCache().version;

package/src/default-tools.json

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

package/src/direct-unity-client.ts

@@ -84,7 +84,7 @@ export class DirectUnityClient {
         cleanup();
         reject(
           new Error(
-            `Request timed out after ${NETWORK_TIMEOUT_MS}ms. Unity may be frozen or busy. [For AI] Run 'uloop focus-window' to bring Unity to the front, then retry the tool. If the issue persists, report this to the user and ask how to proceed. Do NOT kill Unity processes without user permission.`,
+            `Request timed out after ${NETWORK_TIMEOUT_MS}ms. Unity may be frozen or busy. [For AI] Report this to the user and ask how to proceed.`,
           ),
         );
       }, NETWORK_TIMEOUT_MS);

package/src/port-resolver.ts

@@ -15,7 +15,6 @@ const DEFAULT_PORT = 8700;
 
 interface UnityMcpSettings {
   isServerRunning?: boolean;
-  serverPort?: number;
   customPort?: number;
 }
 
@@ -36,21 +35,12 @@ function normalizePort(port: unknown): number | null {
 }
 
 export function resolvePortFromUnitySettings(settings: UnityMcpSettings): number | null {
-  const serverPort = normalizePort(settings.serverPort);
   const customPort = normalizePort(settings.customPort);
 
-  if (settings.isServerRunning === true && serverPort !== null) {
-    return serverPort;
-  }
-
   if (customPort !== null) {
     return customPort;
   }
 
-  if (serverPort !== null) {
-    return serverPort;
-  }
-
   return null;
 }
 

package/src/project-root.ts

@@ -113,17 +113,27 @@ function findUnityProjectInParents(startPath: string): string | null {
  *
  * Returns null if no Unity project is found.
  */
+let hasWarnedMultipleProjects = false;
+
+/** @internal Reset warning state for testing */
+export function resetMultipleProjectsWarning(): void {
+  hasWarnedMultipleProjects = false;
+}
+
 export function findUnityProjectRoot(startPath: string = process.cwd()): string | null {
   const childProjects = findUnityProjectsInChildren(startPath, CHILD_SEARCH_MAX_DEPTH);
 
   if (childProjects.length > 0) {
-    if (childProjects.length > 1) {
+    if (childProjects.length > 1 && !hasWarnedMultipleProjects) {
+      hasWarnedMultipleProjects = true;
       /* eslint-disable no-console -- CLI user-facing warning output */
       console.error('\x1b[33mWarning: Multiple Unity projects found in child directories:\x1b[0m');
       for (const project of childProjects) {
         console.error(`  - ${project}`);
       }
-      console.error(`\x1b[33mUsing: ${childProjects[0]}\x1b[0m`);
+      console.error(
+        '\x1b[33mRun from a Unity project root or use --project-path to specify one.\x1b[0m',
+      );
       console.error('');
       /* eslint-enable no-console */
     }

package/src/skills/skills-command.ts

@@ -19,6 +19,9 @@ interface SkillsOptions {
   global?: boolean;
   claude?: boolean;
   codex?: boolean;
+  cursor?: boolean;
+  gemini?: boolean;
+  windsurf?: boolean;
 }
 
 export function registerSkillsCommand(program: Command): void {
@@ -32,6 +35,9 @@ export function registerSkillsCommand(program: Command): void {
     .option('-g, --global', 'Check global installation')
     .option('--claude', 'Check Claude Code installation')
     .option('--codex', 'Check Codex CLI installation')
+    .option('--cursor', 'Check Cursor installation')
+    .option('--gemini', 'Check Gemini CLI installation')
+    .option('--windsurf', 'Check Windsurf installation')
     .action((options: SkillsOptions) => {
       const targets = resolveTargets(options);
       const global = options.global ?? false;
@@ -44,6 +50,9 @@ export function registerSkillsCommand(program: Command): void {
     .option('-g, --global', 'Install to global location')
     .option('--claude', 'Install to Claude Code')
     .option('--codex', 'Install to Codex CLI')
+    .option('--cursor', 'Install to Cursor')
+    .option('--gemini', 'Install to Gemini CLI')
+    .option('--windsurf', 'Install to Windsurf')
     .action((options: SkillsOptions) => {
       const targets = resolveTargets(options);
       if (targets.length === 0) {
@@ -59,6 +68,9 @@ export function registerSkillsCommand(program: Command): void {
     .option('-g, --global', 'Uninstall from global location')
     .option('--claude', 'Uninstall from Claude Code')
     .option('--codex', 'Uninstall from Codex CLI')
+    .option('--cursor', 'Uninstall from Cursor')
+    .option('--gemini', 'Uninstall from Gemini CLI')
+    .option('--windsurf', 'Uninstall from Windsurf')
     .action((options: SkillsOptions) => {
       const targets = resolveTargets(options);
       if (targets.length === 0) {
@@ -77,6 +89,15 @@ function resolveTargets(options: SkillsOptions): TargetConfig[] {
   if (options.codex) {
     targets.push(getTargetConfig('codex'));
   }
+  if (options.cursor) {
+    targets.push(getTargetConfig('cursor'));
+  }
+  if (options.gemini) {
+    targets.push(getTargetConfig('gemini'));
+  }
+  if (options.windsurf) {
+    targets.push(getTargetConfig('windsurf'));
+  }
   return targets;
 }
 
@@ -86,14 +107,17 @@ function showTargetGuidance(command: string): void {
   console.log('Available targets:');
   console.log('  --claude   Claude Code (.claude/skills/)');
   console.log('  --codex    Codex CLI (.codex/skills/)');
+  console.log('  --cursor   Cursor (.cursor/skills/)');
+  console.log('  --gemini   Gemini CLI (.gemini/skills/)');
+  console.log('  --windsurf Windsurf (.windsurf/skills/)');
   console.log('');
   console.log('Options:');
-  console.log('  -g, --global   Use global location (~/.claude/ or ~/.codex/)');
+  console.log('  -g, --global   Use global location');
   console.log('');
   console.log('Examples:');
   console.log(`  uloop skills ${command} --claude`);
-  console.log(`  uloop skills ${command} --codex --global`);
-  console.log(`  uloop skills ${command} --claude --codex`);
+  console.log(`  uloop skills ${command} --cursor --global`);
+  console.log(`  uloop skills ${command} --claude --codex --cursor --gemini`);
 }
 
 function listSkills(targets: TargetConfig[], global: boolean): void {

package/src/skills/target-config.ts

@@ -3,7 +3,7 @@
  * Supports Claude Code and Codex CLI, with extensibility for future targets.
  */
 
-export type TargetId = 'claude' | 'codex';
+export type TargetId = 'claude' | 'codex' | 'cursor' | 'gemini' | 'windsurf';
 
 export interface TargetConfig {
   id: TargetId;
@@ -25,9 +25,27 @@ export const TARGET_CONFIGS: Record<TargetId, TargetConfig> = {
     projectDir: '.codex',
     skillFileName: 'SKILL.md',
   },
+  cursor: {
+    id: 'cursor',
+    displayName: 'Cursor',
+    projectDir: '.cursor',
+    skillFileName: 'SKILL.md',
+  },
+  gemini: {
+    id: 'gemini',
+    displayName: 'Gemini CLI',
+    projectDir: '.gemini',
+    skillFileName: 'SKILL.md',
+  },
+  windsurf: {
+    id: 'windsurf',
+    displayName: 'Windsurf',
+    projectDir: '.windsurf',
+    skillFileName: 'SKILL.md',
+  },
 };
 
-export const ALL_TARGET_IDS: TargetId[] = ['claude', 'codex'];
+export const ALL_TARGET_IDS: TargetId[] = ['claude', 'codex', 'cursor', 'gemini', 'windsurf'];
 
 export function getTargetConfig(id: TargetId): TargetConfig {
   // eslint-disable-next-line security/detect-object-injection -- id is type-constrained to TargetId union type

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