uloop-cli 0.68.2 → 0.68.3

package/package.json

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

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/cli.ts

@@ -12,7 +12,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from '
 import { join, basename, dirname } from 'path';
 import { homedir } from 'os';
 import { spawn } from 'child_process';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import {
   executeToolCommand,
   listAvailableTools,
@@ -24,6 +24,7 @@ import {
   loadToolsCache,
   hasCacheFile,
   getDefaultTools,
+  getDefaultToolNames,
   ToolDefinition,
   ToolProperty,
   getCachedServerVersion,
@@ -45,6 +46,16 @@ const FOCUS_WINDOW_COMMAND = 'focus-window' as const;
 const LAUNCH_COMMAND = 'launch' as const;
 const UPDATE_COMMAND = 'update' as const;
 
+const HELP_GROUP_BUILTIN_TOOLS = 'Built-in Tools:' as const;
+const HELP_GROUP_THIRD_PARTY_TOOLS = 'Third-party Tools:' as const;
+const HELP_GROUP_CLI_COMMANDS = 'CLI Commands:' as const;
+
+const HELP_GROUP_ORDER = [
+  HELP_GROUP_CLI_COMMANDS,
+  HELP_GROUP_BUILTIN_TOOLS,
+  HELP_GROUP_THIRD_PARTY_TOOLS,
+] as const;
+
 // commander.js built-in flags that exit immediately without needing Unity
 const NO_SYNC_FLAGS = ['-v', '--version', '-h', '--help'] as const;
 
@@ -66,7 +77,44 @@ program
   .description('Unity MCP CLI - Direct communication with Unity Editor')
   .version(VERSION, '-v, --version', 'Output the version number')
   .showHelpAfterError('(run with -h for available options)')
-  .configureHelp({ sortSubcommands: true });
+  .configureHelp({
+    sortSubcommands: true,
+    // commander.js default groupItems determines group display order by registration order,
+    // but CLI commands are registered at module level (before tools), so the default order
+    // would be wrong. We re-implement to enforce HELP_GROUP_ORDER.
+    groupItems<T extends Command | Option>(
+      unsortedItems: T[],
+      visibleItems: T[],
+      getGroup: (item: T) => string,
+    ): Map<string, T[]> {
+      const groupMap = new Map<string, T[]>();
+      for (const item of unsortedItems) {
+        const group: string = getGroup(item);
+        if (!groupMap.has(group)) {
+          groupMap.set(group, []);
+        }
+      }
+      for (const item of visibleItems) {
+        const group: string = getGroup(item);
+        if (!groupMap.has(group)) {
+          groupMap.set(group, []);
+        }
+        groupMap.get(group)!.push(item);
+      }
+      const ordered = new Map<string, T[]>();
+      for (const key of HELP_GROUP_ORDER) {
+        const items: T[] | undefined = groupMap.get(key);
+        if (items !== undefined) {
+          ordered.set(key, items);
+          groupMap.delete(key);
+        }
+      }
+      for (const [key, value] of groupMap) {
+        ordered.set(key, value);
+      }
+      return ordered;
+    },
+  });
 
 // --list-commands: Output command names for shell completion
 program.option('--list-commands', 'List all command names (for shell completion)');
@@ -74,6 +122,12 @@ program.option('--list-commands', 'List all command names (for shell completion)
 // --list-options <cmd>: Output options for a specific command (for shell completion)
 program.option('--list-options <cmd>', 'List options for a command (for shell completion)');
 
+// Set default help group for CLI commands registered at module level
+program.commandsGroup(HELP_GROUP_CLI_COMMANDS);
+// Eagerly initialize the implicit help command so it inherits the CLI Commands group.
+// Without this, the lazy-created help command skips _initCommandGroup and falls into "Commands:" group.
+program.helpCommand(true);
+
 // Built-in commands (not from tools.json)
 program
   .command('list')
@@ -132,12 +186,13 @@ registerLaunchCommand(program);
 /**
  * Register a tool as a CLI command dynamically.
  */
-function registerToolCommand(tool: ToolDefinition): void {
+function registerToolCommand(tool: ToolDefinition, helpGroup: string): void {
   // Skip if already registered as a built-in command
   if (BUILTIN_COMMANDS.includes(tool.name as (typeof BUILTIN_COMMANDS)[number])) {
     return;
   }
-  const cmd = program.command(tool.name).description(tool.description);
+  const firstLine: string = tool.description.split('\n')[0];
+  const cmd = program.command(tool.name).description(firstLine).helpGroup(helpGroup);
 
   // Add options from inputSchema.properties
   const properties = tool.inputSchema.properties;
@@ -304,6 +359,10 @@ function convertValue(value: unknown, propInfo: ToolProperty): unknown {
   return value;
 }
 
+function getToolHelpGroup(toolName: string, defaultToolNames: ReadonlySet<string>): string {
+  return defaultToolNames.has(toolName) ? HELP_GROUP_BUILTIN_TOOLS : HELP_GROUP_THIRD_PARTY_TOOLS;
+}
+
 function extractGlobalOptions(options: Record<string, unknown>): GlobalOptions {
   return {
     port: options['port'] as string | undefined,
@@ -788,6 +847,26 @@ function shouldSkipAutoSync(cmdName: string | undefined, args: string[]): boolea
   return args.some((arg) => (NO_SYNC_FLAGS as readonly string[]).includes(arg));
 }
 
+// Options that consume the next argument as a value
+const OPTIONS_WITH_VALUE: ReadonlySet<string> = new Set(['--port', '-p', '--project-path']);
+
+/**
+ * Find the first non-option argument that is not a value of a known option.
+ */
+function findCommandName(args: readonly string[]): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const arg: string = args[i];
+    if (arg.startsWith('-')) {
+      if (OPTIONS_WITH_VALUE.has(arg)) {
+        i++; // skip the next arg (option value)
+      }
+      continue;
+    }
+    return arg;
+  }
+  return undefined;
+}
+
 function extractSyncGlobalOptions(args: string[]): GlobalOptions {
   const options: GlobalOptions = {};
 
@@ -832,8 +911,8 @@ async function main(): Promise<void> {
   }
 
   const args = process.argv.slice(2);
-  const cmdName = args.find((arg) => !arg.startsWith('-'));
   const syncGlobalOptions = extractSyncGlobalOptions(args);
+  const cmdName = findCommandName(args);
 
   // No command name = no Unity operation; skip project detection
   const NO_PROJECT_COMMANDS = [UPDATE_COMMAND, 'completion'] as const;
@@ -841,20 +920,24 @@ async function main(): Promise<void> {
     cmdName === undefined || (NO_PROJECT_COMMANDS as readonly string[]).includes(cmdName);
 
   if (skipProjectDetection) {
-    const defaultTools = getDefaultTools();
+    const defaultToolNames: ReadonlySet<string> = getDefaultToolNames();
     // Only filter disabled tools for top-level help (uloop --help); subcommand help
     // (e.g. uloop completion --help) does not list dynamic tools, so scanning is unnecessary
     const isTopLevelHelp: boolean =
       cmdName === undefined && (args.includes('-h') || args.includes('--help'));
     const shouldFilter: boolean = syncGlobalOptions.projectPath !== undefined || isTopLevelHelp;
+    // Use cache to include third-party tools in help output; falls back to defaults when no cache exists
+    const sourceTools: ToolDefinition[] = shouldFilter
+      ? loadToolsCache(syncGlobalOptions.projectPath).tools
+      : getDefaultTools().tools;
     const tools: ToolDefinition[] = shouldFilter
-      ? filterEnabledTools(defaultTools.tools, syncGlobalOptions.projectPath)
-      : defaultTools.tools;
+      ? filterEnabledTools(sourceTools, syncGlobalOptions.projectPath)
+      : sourceTools;
     if (!shouldFilter || isToolEnabled(FOCUS_WINDOW_COMMAND, syncGlobalOptions.projectPath)) {
-      registerFocusWindowCommand(program);
+      registerFocusWindowCommand(program, HELP_GROUP_BUILTIN_TOOLS);
     }
     for (const tool of tools) {
-      registerToolCommand(tool);
+      registerToolCommand(tool, getToolHelpGroup(tool.name, defaultToolNames));
     }
     program.parse();
     return;
@@ -887,11 +970,12 @@ async function main(): Promise<void> {
   // Register tool commands from cache (after potential auto-sync)
   const toolsCache = loadToolsCache();
   const projectPath: string | undefined = syncGlobalOptions.projectPath;
+  const defaultToolNames: ReadonlySet<string> = getDefaultToolNames();
   if (isToolEnabled(FOCUS_WINDOW_COMMAND, projectPath)) {
-    registerFocusWindowCommand(program);
+    registerFocusWindowCommand(program, HELP_GROUP_BUILTIN_TOOLS);
   }
   for (const tool of filterEnabledTools(toolsCache.tools, projectPath)) {
-    registerToolCommand(tool);
+    registerToolCommand(tool, getToolHelpGroup(tool.name, defaultToolNames));
   }
 
   if (cmdName && !commandExists(cmdName, projectPath)) {
@@ -906,7 +990,7 @@ async function main(): Promise<void> {
       const newCache = loadToolsCache();
       const tool = filterEnabledTools(newCache.tools, projectPath).find((t) => t.name === cmdName);
       if (tool) {
-        registerToolCommand(tool);
+        registerToolCommand(tool, getToolHelpGroup(tool.name, defaultToolNames));
         console.log(`\x1b[32m✓ Found '${cmdName}' after sync.\x1b[0m\n`);
       } else {
         console.error(`\x1b[31mError: Command '${cmdName}' not found even after sync.\x1b[0m`);

package/src/commands/focus-window.ts

@@ -12,66 +12,71 @@ 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
+export function registerFocusWindowCommand(program: Command, helpGroup?: string): void {
+  const cmd = program
     .command('focus-window')
     .description('Bring Unity Editor window to front using OS-level commands')
-    .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({
-            Success: false,
-            Message: 'Unity project not found',
-          }),
-        );
-        process.exit(1);
-      }
+    .option('--project-path <path>', 'Unity project path');
 
-      const runningProcess = await findRunningUnityProcess(projectRoot);
-      if (!runningProcess) {
-        console.error(
-          JSON.stringify({
-            Success: false,
-            Message: 'No running Unity process found for this project',
-          }),
-        );
-        process.exit(1);
-      }
+  if (helpGroup !== undefined) {
+    cmd.helpGroup(helpGroup);
+  }
 
+  cmd.action(async (options: { projectPath?: string }) => {
+    let projectRoot: string | null;
+    if (options.projectPath !== undefined) {
       try {
-        await focusUnityProcess(runningProcess.pid);
-        console.log(
-          JSON.stringify({
-            Success: true,
-            Message: `Unity Editor window focused (PID: ${runningProcess.pid})`,
-          }),
-        );
+        projectRoot = validateProjectPath(options.projectPath);
       } catch (error) {
         console.error(
           JSON.stringify({
             Success: false,
-            Message: `Failed to focus Unity window: ${error instanceof Error ? error.message : String(error)}`,
+            Message: error instanceof Error ? error.message : String(error),
           }),
         );
         process.exit(1);
+        return;
       }
-    });
+    } else {
+      projectRoot = findUnityProjectRoot();
+    }
+    if (projectRoot === null) {
+      console.error(
+        JSON.stringify({
+          Success: false,
+          Message: 'Unity project not found',
+        }),
+      );
+      process.exit(1);
+    }
+
+    const runningProcess = await findRunningUnityProcess(projectRoot);
+    if (!runningProcess) {
+      console.error(
+        JSON.stringify({
+          Success: false,
+          Message: 'No running Unity process found for this project',
+        }),
+      );
+      process.exit(1);
+    }
+
+    try {
+      await focusUnityProcess(runningProcess.pid);
+      console.log(
+        JSON.stringify({
+          Success: true,
+          Message: `Unity Editor window focused (PID: ${runningProcess.pid})`,
+        }),
+      );
+    } catch (error) {
+      console.error(
+        JSON.stringify({
+          Success: false,
+          Message: `Failed to focus Unity window: ${error instanceof Error ? error.message : String(error)}`,
+        }),
+      );
+      process.exit(1);
+    }
+  });
 }

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.68.2",
+  "version": "0.68.3",
   "tools": [
     {
       "name": "compile",
@@ -239,6 +239,34 @@
         }
       }
     },
+    {
+      "name": "get-unity-search-providers",
+      "description": "Get detailed information about Unity Search providers including display names, descriptions, active status, and capabilities",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "ProviderId": {
+            "type": "string",
+            "description": "Specific provider ID to get details for (empty = all providers). Examples: 'asset', 'scene', 'menu', 'settings'"
+          },
+          "ActiveOnly": {
+            "type": "boolean",
+            "description": "Whether to include only active providers",
+            "default": false
+          },
+          "SortByPriority": {
+            "type": "boolean",
+            "description": "Sort providers by priority (lower number = higher priority)",
+            "default": true
+          },
+          "IncludeDescriptions": {
+            "type": "boolean",
+            "description": "Include detailed descriptions for each provider",
+            "default": true
+          }
+        }
+      }
+    },
     {
       "name": "get-menu-items",
       "description": "Retrieve Unity MenuItems",

package/src/skills/deprecated-skills.ts

@@ -6,5 +6,5 @@
  */
 export const DEPRECATED_SKILLS: string[] = [
   'uloop-capture-window', // renamed to uloop-screenshot in v0.54.0
-  'uloop-get-provider-details', // internal development-only tool, not for end users
+  'uloop-get-provider-details', // renamed to uloop-get-unity-search-providers
 ];

package/src/tool-cache.ts

@@ -41,7 +41,10 @@ export interface ToolsCache {
 const CACHE_DIR = '.uloop';
 const CACHE_FILE = 'tools.json';
 
-function getCacheDir(): string {
+function getCacheDir(projectPath?: string): string {
+  if (projectPath !== undefined) {
+    return join(projectPath, CACHE_DIR);
+  }
   const projectRoot = findUnityProjectRoot();
   if (projectRoot === null) {
     return join(process.cwd(), CACHE_DIR);
@@ -49,8 +52,8 @@ function getCacheDir(): string {
   return join(projectRoot, CACHE_DIR);
 }
 
-function getCachePath(): string {
-  return join(getCacheDir(), CACHE_FILE);
+function getCachePath(projectPath?: string): string {
+  return join(getCacheDir(projectPath), CACHE_FILE);
 }
 
 /**
@@ -62,9 +65,10 @@ export function getDefaultTools(): ToolsCache {
 
 /**
  * Load tools from cache file, falling back to default tools if cache doesn't exist.
+ * When projectPath is specified, reads cache from that project directory.
  */
-export function loadToolsCache(): ToolsCache {
-  const cachePath = getCachePath();
+export function loadToolsCache(projectPath?: string): ToolsCache {
+  const cachePath = getCachePath(projectPath);
 
   if (existsSync(cachePath)) {
     try {
@@ -107,6 +111,15 @@ export function getCacheFilePath(): string {
   return getCachePath();
 }
 
+/**
+ * Get the set of default tool names bundled with npm package.
+ * Used to distinguish built-in tools from third-party tools.
+ */
+export function getDefaultToolNames(): ReadonlySet<string> {
+  const defaultTools: ToolsCache = getDefaultTools();
+  return new Set(defaultTools.tools.map((tool: ToolDefinition) => tool.name));
+}
+
 /**
  * Get the Unity server version from cache file.
  * Returns undefined if cache doesn't exist, is corrupted, or serverVersion is missing.

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