uloop-cli 0.44.2 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.44.2",
+  "version": "0.45.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",

package/src/arg-parser.ts

@@ -3,6 +3,9 @@
  * 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;

package/src/cli.ts

@@ -4,7 +4,11 @@
  * Commands are dynamically registered from tools.json cache.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+// CLI tools output to console by design, file paths are constructed from trusted sources (project root detection),
+// and object keys come from tool definitions which are internal trusted data
+/* eslint-disable no-console, security/detect-non-literal-fs-filename, security/detect-object-injection */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
 import { join, basename, dirname } from 'path';
 import { homedir } from 'os';
 import { spawn } from 'child_process';
@@ -25,7 +29,7 @@ interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
 }
 
-const BUILTIN_COMMANDS = ['list', 'sync', 'completion', 'update', 'skills'] as const;
+const BUILTIN_COMMANDS = ['list', 'sync', 'completion', 'update', 'fix', 'skills'] as const;
 
 const program = new Command();
 
@@ -73,6 +77,13 @@ program
     updateCli();
   });
 
+program
+  .command('fix')
+  .description('Clean up stale lock files that may prevent CLI from connecting')
+  .action(() => {
+    cleanupLockFiles();
+  });
+
 // Register skills subcommand
 registerSkillsCommand(program);
 
@@ -202,29 +213,39 @@ function extractGlobalOptions(options: Record<string, unknown>): GlobalOptions {
   };
 }
 
-function isDomainReloadLockFilePresent(): boolean {
-  const projectRoot = findUnityProjectRoot();
-  if (projectRoot === null) {
-    return false;
-  }
-  const lockPath = join(projectRoot, 'Temp', 'domainreload.lock');
-  return existsSync(lockPath);
-}
-
 async function runWithErrorHandling(fn: () => Promise<void>): Promise<void> {
   try {
     await fn();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
 
+    if (message === 'UNITY_COMPILING') {
+      console.error('\x1b[33m⏳ Unity is compiling scripts.\x1b[0m');
+      console.error('Please wait for compilation to finish and try again.');
+      process.exit(1);
+    }
+
+    if (message === 'UNITY_DOMAIN_RELOAD') {
+      console.error('\x1b[33m⏳ Unity is reloading (Domain Reload in progress).\x1b[0m');
+      console.error('Please wait a moment and try again.');
+      process.exit(1);
+    }
+
+    if (message === 'UNITY_SERVER_STARTING') {
+      console.error('\x1b[33m⏳ Unity server is starting.\x1b[0m');
+      console.error('Please wait a moment and try again.');
+      process.exit(1);
+    }
+
+    if (message === 'UNITY_NO_RESPONSE') {
+      console.error('\x1b[33m⏳ Unity is busy (no response received).\x1b[0m');
+      console.error('Unity may be compiling, reloading, or starting. Please wait and try again.');
+      process.exit(1);
+    }
+
     if (message.includes('ECONNREFUSED')) {
-      if (isDomainReloadLockFilePresent()) {
-        console.error('\x1b[33m⏳ Unity is reloading (Domain Reload in progress).\x1b[0m');
-        console.error('Please wait a moment and try again.');
-      } else {
-        console.error('\x1b[31mError: Cannot connect to Unity.\x1b[0m');
-        console.error('Make sure Unity is running with uLoopMCP installed.');
-      }
+      console.error('\x1b[31mError: Cannot connect to Unity.\x1b[0m');
+      console.error('Make sure Unity is running with uLoopMCP installed.');
       process.exit(1);
     }
 
@@ -334,7 +355,6 @@ compdef _uloop uloop`;
  * Update uloop CLI to the latest version using npm.
  */
 function updateCli(): void {
-  // eslint-disable-next-line no-console
   console.log('Updating uloop-cli to the latest version...');
 
   const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
@@ -345,24 +365,51 @@ function updateCli(): void {
 
   child.on('close', (code) => {
     if (code === 0) {
-      // eslint-disable-next-line no-console
       console.log('\n✅ uloop-cli has been updated successfully!');
-      // eslint-disable-next-line no-console
       console.log('Run "uloop --version" to check the new version.');
     } else {
-      // eslint-disable-next-line no-console
       console.error(`\n❌ Update failed with exit code ${code}`);
       process.exit(1);
     }
   });
 
   child.on('error', (err) => {
-    // eslint-disable-next-line no-console
     console.error(`❌ Failed to run npm: ${err.message}`);
     process.exit(1);
   });
 }
 
+const LOCK_FILES = ['compiling.lock', 'domainreload.lock', 'serverstarting.lock'] as const;
+
+/**
+ * Clean up stale lock files that may prevent CLI from connecting to Unity.
+ */
+function cleanupLockFiles(): void {
+  const projectRoot = findUnityProjectRoot();
+  if (projectRoot === null) {
+    console.error('Could not find Unity project root.');
+    process.exit(1);
+  }
+
+  const tempDir = join(projectRoot, 'Temp');
+  let cleaned = 0;
+
+  for (const lockFile of LOCK_FILES) {
+    const lockPath = join(tempDir, lockFile);
+    if (existsSync(lockPath)) {
+      unlinkSync(lockPath);
+      console.log(`Removed: ${lockFile}`);
+      cleaned++;
+    }
+  }
+
+  if (cleaned === 0) {
+    console.log('No lock files found.');
+  } else {
+    console.log(`\n✅ Cleaned up ${cleaned} lock file(s).`);
+  }
+}
+
 /**
  * Handle completion command.
  */

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.44.2",
+  "version": "0.45.0",
   "tools": [
     {
       "name": "compile",

package/src/direct-unity-client.ts

@@ -3,6 +3,9 @@
  * Establishes one-shot TCP connections to Unity without going through MCP server.
  */
 
+// Non-null assertions are used after TCP frame parsing where data existence is guaranteed by protocol
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+
 import * as net from 'net';
 import { createFrame, parseFrameFromBuffer, extractFrameFromBuffer } from './simple-framer.js';
 

package/src/execute-tool.ts

@@ -3,15 +3,99 @@
  * Handles dynamic tool execution by connecting to Unity and sending requests.
  */
 
+// CLI tools output to console by design, object keys come from Unity tool responses which are trusted,
+// and lock file paths are constructed from trusted project root detection
+/* eslint-disable no-console, security/detect-object-injection, security/detect-non-literal-fs-filename */
+
+import * as readline from 'readline';
+import { existsSync } from 'fs';
+import { join } from 'path';
 import { DirectUnityClient } from './direct-unity-client.js';
 import { resolveUnityPort } from './port-resolver.js';
 import { saveToolsCache, getCacheFilePath, ToolsCache, ToolDefinition } from './tool-cache.js';
 import { VERSION } from './version.js';
+import { createSpinner } from './spinner.js';
+import { findUnityProjectRoot } from './project-root.js';
+
+/**
+ * Suppress stdin echo during async operation to prevent escape sequences from being displayed.
+ * Returns a cleanup function to restore stdin state.
+ */
+function suppressStdinEcho(): () => void {
+  if (!process.stdin.isTTY) {
+    return () => {};
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  const onData = (data: Buffer): void => {
+    // Ctrl+C (0x03) should trigger process exit
+    if (data[0] === 0x03) {
+      process.exit(130);
+    }
+  };
+  process.stdin.on('data', onData);
+
+  return () => {
+    process.stdin.off('data', onData);
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+    rl.close();
+  };
+}
 
 export interface GlobalOptions {
   port?: string;
 }
 
+const RETRY_DELAY_MS = 500;
+const MAX_RETRIES = 3;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryableError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const message = error.message;
+  return message.includes('ECONNREFUSED') || message === 'UNITY_NO_RESPONSE';
+}
+
+/**
+ * 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();
+  if (projectRoot === null) {
+    return;
+  }
+
+  const compilingLock = join(projectRoot, 'Temp', 'compiling.lock');
+  if (existsSync(compilingLock)) {
+    throw new Error('UNITY_COMPILING');
+  }
+
+  const domainReloadLock = join(projectRoot, 'Temp', 'domainreload.lock');
+  if (existsSync(domainReloadLock)) {
+    throw new Error('UNITY_DOMAIN_RELOAD');
+  }
+
+  const serverStartingLock = join(projectRoot, 'Temp', 'serverstarting.lock');
+  if (existsSync(serverStartingLock)) {
+    throw new Error('UNITY_SERVER_STARTING');
+  }
+}
+
 export async function executeToolCommand(
   toolName: string,
   params: Record<string, unknown>,
@@ -27,18 +111,46 @@ export async function executeToolCommand(
   }
   const port = await resolveUnityPort(portNumber);
 
-  const client = new DirectUnityClient(port);
+  const restoreStdin = suppressStdinEcho();
+  const spinner = createSpinner('Connecting to Unity...');
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    checkUnityBusyState();
+
+    const client = new DirectUnityClient(port);
+    try {
+      await client.connect();
+
+      spinner.update(`Executing ${toolName}...`);
+      const result = await client.sendRequest(toolName, params);
 
-  try {
-    await client.connect();
+      if (result === undefined || result === null) {
+        throw new Error('UNITY_NO_RESPONSE');
+      }
 
-    const result = await client.sendRequest(toolName, params);
+      // Success - stop spinner and output result
+      spinner.stop();
+      restoreStdin();
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    } catch (error) {
+      lastError = error;
+      client.disconnect();
 
-    // Always output JSON to match MCP response format
-    console.log(JSON.stringify(result, null, 2));
-  } finally {
-    client.disconnect();
+      if (!isRetryableError(error) || attempt >= MAX_RETRIES) {
+        break;
+      }
+      spinner.update('Retrying connection...');
+      await sleep(RETRY_DELAY_MS);
+    } finally {
+      client.disconnect();
+    }
   }
+
+  spinner.stop();
+  restoreStdin();
+  throw lastError;
 }
 
 export async function listAvailableTools(globalOptions: GlobalOptions): Promise<void> {
@@ -52,25 +164,50 @@ export async function listAvailableTools(globalOptions: GlobalOptions): Promise<
   }
   const port = await resolveUnityPort(portNumber);
 
-  const client = new DirectUnityClient(port);
+  const restoreStdin = suppressStdinEcho();
+  const spinner = createSpinner('Connecting to Unity...');
 
-  try {
-    await client.connect();
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    checkUnityBusyState();
 
-    const result = await client.sendRequest<{
-      Tools: Array<{ name: string; description: string }>;
-    }>('get-tool-details', { IncludeDevelopmentOnly: false });
+    const client = new DirectUnityClient(port);
+    try {
+      await client.connect();
 
-    if (!result.Tools || !Array.isArray(result.Tools)) {
-      throw new Error('Unexpected response from Unity: missing Tools array');
-    }
+      spinner.update('Fetching tool list...');
+      const result = await client.sendRequest<{
+        Tools: Array<{ name: string; description: string }>;
+      }>('get-tool-details', { IncludeDevelopmentOnly: false });
 
-    for (const tool of result.Tools) {
-      console.log(`  - ${tool.name}`);
+      if (!result.Tools || !Array.isArray(result.Tools)) {
+        throw new Error('Unexpected response from Unity: missing Tools array');
+      }
+
+      // Success - stop spinner and output result
+      spinner.stop();
+      restoreStdin();
+      for (const tool of result.Tools) {
+        console.log(`  - ${tool.name}`);
+      }
+      return;
+    } catch (error) {
+      lastError = error;
+      client.disconnect();
+
+      if (!isRetryableError(error) || attempt >= MAX_RETRIES) {
+        break;
+      }
+      spinner.update('Retrying connection...');
+      await sleep(RETRY_DELAY_MS);
+    } finally {
+      client.disconnect();
     }
-  } finally {
-    client.disconnect();
   }
+
+  spinner.stop();
+  restoreStdin();
+  throw lastError;
 }
 
 interface UnityToolInfo {
@@ -115,41 +252,66 @@ export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
   }
   const port = await resolveUnityPort(portNumber);
 
-  const client = new DirectUnityClient(port);
+  const restoreStdin = suppressStdinEcho();
+  const spinner = createSpinner('Connecting to Unity...');
 
-  try {
-    await client.connect();
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    checkUnityBusyState();
 
-    const result = await client.sendRequest<{
-      Tools: UnityToolInfo[];
-    }>('get-tool-details', { IncludeDevelopmentOnly: false });
+    const client = new DirectUnityClient(port);
+    try {
+      await client.connect();
 
-    if (!result.Tools || !Array.isArray(result.Tools)) {
-      throw new Error('Unexpected response from Unity: missing Tools array');
-    }
+      spinner.update('Syncing tools...');
+      const result = await client.sendRequest<{
+        Tools: UnityToolInfo[];
+      }>('get-tool-details', { IncludeDevelopmentOnly: false });
 
-    const cache: ToolsCache = {
-      version: VERSION,
-      updatedAt: new Date().toISOString(),
-      tools: result.Tools.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-        inputSchema: {
-          type: 'object',
-          properties: convertProperties(tool.parameterSchema.Properties),
-          required: tool.parameterSchema.Required,
-        },
-      })),
-    };
+      spinner.stop();
+      if (!result.Tools || !Array.isArray(result.Tools)) {
+        restoreStdin();
+        throw new Error('Unexpected response from Unity: missing Tools array');
+      }
+
+      const cache: ToolsCache = {
+        version: VERSION,
+        updatedAt: new Date().toISOString(),
+        tools: result.Tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: {
+            type: 'object',
+            properties: convertProperties(tool.parameterSchema.Properties),
+            required: tool.parameterSchema.Required,
+          },
+        })),
+      };
 
-    saveToolsCache(cache);
+      saveToolsCache(cache);
 
-    console.log(`Synced ${cache.tools.length} tools to ${getCacheFilePath()}`);
-    console.log('\nTools:');
-    for (const tool of cache.tools) {
-      console.log(`  - ${tool.name}`);
+      console.log(`Synced ${cache.tools.length} tools to ${getCacheFilePath()}`);
+      console.log('\nTools:');
+      for (const tool of cache.tools) {
+        console.log(`  - ${tool.name}`);
+      }
+      restoreStdin();
+      return;
+    } catch (error) {
+      lastError = error;
+      client.disconnect();
+
+      if (!isRetryableError(error) || attempt >= MAX_RETRIES) {
+        break;
+      }
+      spinner.update('Retrying connection...');
+      await sleep(RETRY_DELAY_MS);
+    } finally {
+      client.disconnect();
     }
-  } finally {
-    client.disconnect();
   }
+
+  spinner.stop();
+  restoreStdin();
+  throw lastError;
 }

package/src/port-resolver.ts

@@ -3,6 +3,9 @@
  * Resolves Unity server port from various sources.
  */
 
+// File paths are constructed from Unity project root detection, not from user input
+/* eslint-disable security/detect-non-literal-fs-filename */
+
 import { readFile } from 'fs/promises';
 import { join } from 'path';
 import { findUnityProjectRoot } from './project-root.js';

package/src/project-root.ts

@@ -3,6 +3,9 @@
  * Searches upward from current directory to find Unity project markers.
  */
 
+// Path traversal is intentional for finding Unity project root by walking up directory tree
+/* eslint-disable security/detect-non-literal-fs-filename */
+
 import { existsSync } from 'fs';
 import { join, dirname } from 'path';
 

package/src/skills/skill-definitions/uloop-compile/SKILL.md

@@ -35,3 +35,13 @@ Returns JSON:
 - `Success`: boolean
 - `ErrorCount`: number
 - `WarningCount`: number
+
+## Troubleshooting
+
+If CLI hangs or shows "Unity is busy" errors after compilation, stale lock files may be preventing connection. Run the following to clean them up:
+
+```bash
+uloop fix
+```
+
+This removes any leftover lock files (`compiling.lock`, `domainreload.lock`, `serverstarting.lock`) from the Unity project's Temp directory.

package/src/skills/skills-command.ts

@@ -2,6 +2,9 @@
  * CLI command definitions for skills management.
  */
 
+// CLI commands output to console by design
+/* eslint-disable no-console */
+
 import { Command } from 'commander';
 import {
   getAllSkillStatuses,

package/src/skills/skills-manager.ts

@@ -2,6 +2,9 @@
  * Skills manager for installing/uninstalling/listing uloop skills.
  */
 
+// File paths are constructed from home directory and skill names, not from untrusted user input
+/* eslint-disable security/detect-non-literal-fs-filename */
+
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';

package/src/spinner.ts

@@ -0,0 +1,49 @@
+/**
+ * Terminal spinner for showing loading state during async operations.
+ */
+
+// Array index access is safe here (modulo operation keeps it in bounds)
+/* eslint-disable security/detect-object-injection */
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const;
+const FRAME_INTERVAL_MS = 80;
+
+export interface Spinner {
+  update(message: string): void;
+  stop(): void;
+}
+
+/**
+ * Create a terminal spinner that displays a rotating animation with a message.
+ * Returns a Spinner object with update() and stop() methods.
+ */
+export function createSpinner(initialMessage: string): Spinner {
+  if (!process.stderr.isTTY) {
+    return {
+      update: (): void => {},
+      stop: (): void => {},
+    };
+  }
+
+  let frameIndex = 0;
+  let currentMessage = initialMessage;
+
+  const render = (): void => {
+    const frame = SPINNER_FRAMES[frameIndex];
+    process.stderr.write(`\r\x1b[K${frame} ${currentMessage}`);
+    frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+  };
+
+  render();
+  const intervalId = setInterval(render, FRAME_INTERVAL_MS);
+
+  return {
+    update(message: string): void {
+      currentMessage = message;
+    },
+    stop(): void {
+      clearInterval(intervalId);
+      process.stderr.write('\r\x1b[K');
+    },
+  };
+}

package/src/tool-cache.ts

@@ -3,6 +3,9 @@
  * Handles loading/saving tool definitions from .uloop/tools.json cache.
  */
 
+// File paths are constructed from Unity project root, not from untrusted user input
+/* eslint-disable security/detect-non-literal-fs-filename */
+
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import defaultToolsData from './default-tools.json';

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