uloop-cli 0.44.1

package/eslint.config.mjs

@@ -0,0 +1,72 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintPluginPrettier from 'eslint-plugin-prettier/recommended';
+import eslintPluginSecurity from 'eslint-plugin-security';
+
+export default tseslint.config(
+  // Global ignores
+  {
+    ignores: ['dist/', 'node_modules/', '**/*.js', '**/*.d.ts'],
+  },
+
+  // Base ESLint recommended rules
+  eslint.configs.recommended,
+
+  // TypeScript ESLint recommended rules
+  ...tseslint.configs.recommendedTypeChecked,
+
+  // Prettier integration
+  eslintPluginPrettier,
+
+  // Security plugin
+  {
+    plugins: {
+      security: eslintPluginSecurity,
+    },
+  },
+
+  // Main configuration for TypeScript files
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Prettier
+      'prettier/prettier': 'error',
+
+      // TypeScript rules
+      '@typescript-eslint/explicit-function-return-type': 'error',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+
+      // General rules
+      'no-console': 'warn',
+      'no-debugger': 'error',
+      'no-var': 'error',
+      'prefer-const': 'error',
+      eqeqeq: ['error', 'always'],
+      curly: ['error', 'all'],
+      'no-duplicate-imports': 'error',
+
+      // Security rules
+      'security/detect-eval-with-expression': 'error',
+      'security/detect-non-literal-fs-filename': 'warn',
+      'security/detect-non-literal-regexp': 'warn',
+      'security/detect-non-literal-require': 'error',
+      'security/detect-object-injection': 'warn',
+      'security/detect-possible-timing-attacks': 'warn',
+      'security/detect-pseudoRandomBytes': 'warn',
+      'security/detect-unsafe-regex': 'error',
+      'security/detect-buffer-noassert': 'error',
+      'security/detect-child-process': 'warn',
+      'security/detect-disable-mustache-escape': 'error',
+      'security/detect-new-buffer': 'error',
+      'security/detect-no-csrf-before-method-override': 'error',
+    },
+  },
+);

package/jest.config.cjs

@@ -0,0 +1,19 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/__tests__/**',
+  ],
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "uloop-cli",
+  "version": "0.44.1",
+  "//version": "x-release-please-version",
+  "description": "CLI tool for Unity Editor communication via uLoopMCP",
+  "main": "dist/cli.bundle.cjs",
+  "bin": {
+    "uloop": "./dist/cli.bundle.cjs"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=cjs --outfile=dist/cli.bundle.cjs --sourcemap --banner:js='#!/usr/bin/env node' --loader:.md=text",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write src/**/*.ts",
+    "format:check": "prettier --check src/**/*.ts",
+    "test:cli": "jest src/__tests__ --testTimeout=60000 --runInBand"
+  },
+  "keywords": [
+    "cli",
+    "unity",
+    "mcp",
+    "uloop"
+  ],
+  "author": "hatayama",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hatayama/uLoopMCP.git",
+    "directory": "Packages/src/Cli~"
+  },
+  "bugs": {
+    "url": "https://github.com/hatayama/uLoopMCP/issues"
+  },
+  "homepage": "https://github.com/hatayama/uLoopMCP#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "commander": "^14.0.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.2",
+    "@types/jest": "30.0.0",
+    "@types/node": "25.0.2",
+    "esbuild": "0.27.1",
+    "eslint": "9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-security": "3.0.1",
+    "jest": "30.2.0",
+    "prettier": "3.7.4",
+    "ts-jest": "29.4.6",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.49.0"
+  }
+}

package/src/__tests__/cli-e2e.test.ts

@@ -0,0 +1,349 @@
+/**
+ * CLI End-to-End Tests
+ *
+ * These tests require a running Unity Editor with uLoopMCP installed.
+ * Run from Unity project root: npm run test:cli
+ *
+ * @jest-environment node
+ */
+
+import { execSync, ExecSyncOptionsWithStringEncoding } from 'child_process';
+import { join } from 'path';
+
+const CLI_PATH = join(__dirname, '../..', 'dist/cli.bundle.cjs');
+
+const UNITY_PROJECT_ROOT = join(__dirname, '../../../../..');
+
+const EXEC_OPTIONS: ExecSyncOptionsWithStringEncoding = {
+  encoding: 'utf-8',
+  timeout: 60000,
+  cwd: UNITY_PROJECT_ROOT,
+  stdio: ['pipe', 'pipe', 'pipe'],
+};
+
+const INTERVAL_MS = 1500;
+const DOMAIN_RELOAD_RETRY_MS = 3000;
+const DOMAIN_RELOAD_MAX_RETRIES = 3;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function sleepSync(ms: number): void {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    // busy wait
+  }
+}
+
+function isDomainReloadError(output: string): boolean {
+  return output.includes('Unity is reloading') || output.includes('Domain Reload');
+}
+
+function runCli(args: string): { stdout: string; stderr: string; exitCode: number } {
+  try {
+    const stdout = execSync(`node "${CLI_PATH}" ${args}`, EXEC_OPTIONS);
+    return { stdout, stderr: '', exitCode: 0 };
+  } catch (error) {
+    const execError = error as { stdout?: string; stderr?: string; status?: number };
+    return {
+      stdout: execError.stdout ?? '',
+      stderr: execError.stderr ?? '',
+      exitCode: execError.status ?? 1,
+    };
+  }
+}
+
+function runCliWithRetry(args: string): { stdout: string; stderr: string; exitCode: number } {
+  for (let attempt = 0; attempt < DOMAIN_RELOAD_MAX_RETRIES; attempt++) {
+    const result = runCli(args);
+    const output = result.stderr || result.stdout;
+
+    if (result.exitCode === 0 || !isDomainReloadError(output)) {
+      return result;
+    }
+
+    // Domain Reload in progress, wait and retry
+    if (attempt < DOMAIN_RELOAD_MAX_RETRIES - 1) {
+      sleepSync(DOMAIN_RELOAD_RETRY_MS);
+    }
+  }
+
+  return runCli(args);
+}
+
+function runCliJson<T>(args: string): T {
+  const { stdout, stderr, exitCode } = runCliWithRetry(args);
+  if (exitCode !== 0) {
+    throw new Error(`CLI failed with exit code ${exitCode}: ${stderr || stdout}`);
+  }
+  return JSON.parse(stdout) as T;
+}
+
+describe('CLI E2E Tests (requires running Unity)', () => {
+  beforeEach(async () => {
+    await sleep(INTERVAL_MS);
+  });
+
+  describe('compile', () => {
+    it('should compile successfully', () => {
+      const result = runCliJson<{ Success: boolean; ErrorCount: number }>('compile');
+
+      expect(result.Success).toBe(true);
+      expect(result.ErrorCount).toBe(0);
+    });
+
+    it('should support --force-recompile option', () => {
+      const { exitCode } = runCli('compile --force-recompile');
+
+      // Domain Reload causes connection to be lost, so we just verify the command runs
+      // The exit code may be non-zero due to connection being dropped during reload
+      expect(typeof exitCode).toBe('number');
+    });
+  });
+
+  describe('get-logs', () => {
+    const TEST_LOG_MENU_PATH = 'uLoopMCP/Debug/LogGetter Tests/Output Test Logs';
+
+    function setupTestLogs(): void {
+      runCli('clear-console');
+      runCli(`execute-menu-item --menu-item-path "${TEST_LOG_MENU_PATH}"`);
+    }
+
+    it('should retrieve test logs after executing Output Test Logs menu item', () => {
+      setupTestLogs();
+
+      const result = runCliJson<{ TotalCount: number; Logs: Array<{ Message: string }> }>(
+        'get-logs',
+      );
+
+      expect(result.TotalCount).toBeGreaterThan(0);
+      expect(Array.isArray(result.Logs)).toBe(true);
+
+      // Verify specific test log messages exist
+      const messages = result.Logs.map((log) => log.Message);
+      expect(messages.some((m) => m.includes('This is a normal log'))).toBe(true);
+      expect(messages.some((m) => m.includes('LogGetter test complete'))).toBe(true);
+    });
+
+    it('should respect --max-count option', () => {
+      setupTestLogs();
+
+      const result = runCliJson<{ Logs: unknown[] }>('get-logs --max-count 3');
+
+      expect(result.Logs.length).toBeLessThanOrEqual(3);
+    });
+
+    it('should filter by log type Warning', () => {
+      setupTestLogs();
+
+      const result = runCliJson<{ Logs: Array<{ Type: string; Message: string }> }>(
+        'get-logs --log-type Warning',
+      );
+
+      expect(result.Logs.length).toBeGreaterThan(0);
+      for (const log of result.Logs) {
+        expect(log.Type).toBe('Warning');
+      }
+      // Verify test warning log exists
+      const messages = result.Logs.map((log) => log.Message);
+      expect(messages.some((m) => m.includes('This is a warning log'))).toBe(true);
+    });
+
+    it('should filter by log type Error', () => {
+      setupTestLogs();
+
+      const result = runCliJson<{ Logs: Array<{ Type: string; Message: string }> }>(
+        'get-logs --log-type Error',
+      );
+
+      expect(result.Logs.length).toBeGreaterThan(0);
+      for (const log of result.Logs) {
+        expect(log.Type).toBe('Error');
+      }
+      // Verify test error log exists
+      const messages = result.Logs.map((log) => log.Message);
+      expect(messages.some((m) => m.includes('This is an error log'))).toBe(true);
+    });
+
+    it('should search logs by text', () => {
+      setupTestLogs();
+
+      const result = runCliJson<{ Logs: Array<{ Message: string }> }>(
+        'get-logs --search-text "LogGetter test complete"',
+      );
+
+      expect(result.Logs.length).toBeGreaterThan(0);
+      for (const log of result.Logs) {
+        expect(log.Message).toContain('LogGetter test complete');
+      }
+    });
+  });
+
+  describe('clear-console', () => {
+    const TEST_LOG_MENU_PATH = 'uLoopMCP/Debug/LogGetter Tests/Output Test Logs';
+
+    it('should clear console and verify logs are empty', () => {
+      // First output some logs
+      runCli(`execute-menu-item --menu-item-path "${TEST_LOG_MENU_PATH}"`);
+
+      // Clear console
+      const result = runCliJson<{ Success: boolean }>('clear-console');
+      expect(result.Success).toBe(true);
+
+      // Verify logs are cleared
+      const logsAfterClear = runCliJson<{ TotalCount: number; Logs: unknown[] }>('get-logs');
+      expect(logsAfterClear.TotalCount).toBe(0);
+      expect(logsAfterClear.Logs.length).toBe(0);
+    });
+  });
+
+  describe('focus-window', () => {
+    it('should execute focus-window command', () => {
+      // Note: Success may be false in headless/CI environments where window focus is not supported
+      const result = runCliJson<{ Success: boolean }>('focus-window');
+
+      // Just verify the command executes and returns valid JSON with Success property
+      expect(typeof result.Success).toBe('boolean');
+    });
+  });
+
+  describe('get-hierarchy', () => {
+    it('should retrieve hierarchy and save to file', () => {
+      const result = runCliJson<{ hierarchyFilePath: string }>('get-hierarchy --max-depth 2');
+
+      expect(typeof result.hierarchyFilePath).toBe('string');
+      expect(result.hierarchyFilePath).toContain('hierarchy_');
+    });
+  });
+
+  describe('get-menu-items', () => {
+    it('should retrieve menu items', () => {
+      const result = runCliJson<{ MenuItems: unknown[]; TotalCount: number }>(
+        'get-menu-items --max-count 10',
+      );
+
+      expect(typeof result.TotalCount).toBe('number');
+      expect(Array.isArray(result.MenuItems)).toBe(true);
+    });
+
+    it('should filter menu items', () => {
+      const result = runCliJson<{ MenuItems: Array<{ Path: string }> }>(
+        'get-menu-items --filter-text "GameObject"',
+      );
+
+      expect(result.MenuItems.length).toBeGreaterThan(0);
+      for (const item of result.MenuItems) {
+        expect(item.Path.toLowerCase()).toContain('gameobject');
+      }
+    });
+  });
+
+  describe('execute-menu-item', () => {
+    const TEST_LOG_MENU_PATH = 'uLoopMCP/Debug/LogGetter Tests/Output Test Logs';
+
+    it('should execute menu item and verify logs are output', () => {
+      // Clear console first
+      runCli('clear-console');
+
+      // Execute menu item
+      const result = runCliJson<{ Success: boolean; MenuItemPath: string }>(
+        `execute-menu-item --menu-item-path "${TEST_LOG_MENU_PATH}"`,
+      );
+
+      expect(result.Success).toBe(true);
+      expect(result.MenuItemPath).toBe(TEST_LOG_MENU_PATH);
+
+      // Verify logs were output
+      const logs = runCliJson<{ TotalCount: number; Logs: Array<{ Message: string }> }>('get-logs');
+      expect(logs.TotalCount).toBeGreaterThan(0);
+      const messages = logs.Logs.map((log) => log.Message);
+      expect(messages.some((m) => m.includes('LogGetter test complete'))).toBe(true);
+    });
+  });
+
+  describe('unity-search', () => {
+    it('should search assets', () => {
+      const result = runCliJson<{ Results: unknown[] }>('unity-search --search-query "*.cs"');
+
+      expect(Array.isArray(result.Results)).toBe(true);
+    });
+  });
+
+  describe('find-game-objects', () => {
+    it('should find game objects with name pattern', () => {
+      const result = runCliJson<{ results: unknown[]; totalFound: number }>(
+        'find-game-objects --name-pattern "*" --include-inactive',
+      );
+
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(typeof result.totalFound).toBe('number');
+    });
+  });
+
+  describe('get-provider-details', () => {
+    it('should retrieve search providers', () => {
+      const result = runCliJson<{ Providers: unknown[] }>('get-provider-details');
+
+      expect(Array.isArray(result.Providers)).toBe(true);
+    });
+  });
+
+  describe('--help', () => {
+    it('should display help', () => {
+      const { stdout, exitCode } = runCli('--help');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Unity MCP CLI');
+      expect(stdout).toContain('compile');
+      expect(stdout).toContain('get-logs');
+    });
+
+    it('should display command-specific help', () => {
+      const { stdout, exitCode } = runCli('compile --help');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('--force-recompile');
+    });
+  });
+
+  describe('--version', () => {
+    it('should display version', () => {
+      const { stdout, exitCode } = runCli('--version');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toMatch(/^\d+\.\d+\.\d+/);
+    });
+  });
+
+  describe('list', () => {
+    it('should list available tools', () => {
+      const { stdout, exitCode } = runCli('list');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('- compile');
+      expect(stdout).toContain('- get-logs');
+      expect(stdout).toContain('- get-hierarchy');
+    });
+  });
+
+  describe('sync', () => {
+    it('should sync tools from Unity', () => {
+      const { stdout, exitCode } = runCli('sync');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Synced');
+      expect(stdout).toContain('tools to');
+      // Check for tools.json in path (works for both Windows \ and Unix /)
+      expect(stdout).toMatch(/[/\\]\.uloop[/\\]tools\.json/);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle unknown commands gracefully', () => {
+      const { exitCode } = runCli('unknown-command');
+
+      expect(exitCode).not.toBe(0);
+    });
+  });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,24 @@
+/**
+ * Jest Setup Configuration for CLI tests
+ */
+
+// Suppress console noise during tests (can be overridden in individual tests)
+// eslint-disable-next-line no-console
+const originalConsoleWarn = console.warn;
+// eslint-disable-next-line no-console
+const originalConsoleError = console.error;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  // eslint-disable-next-line no-console
+  console.warn = jest.fn();
+  // eslint-disable-next-line no-console
+  console.error = jest.fn();
+});
+
+afterEach(() => {
+  // eslint-disable-next-line no-console
+  console.warn = originalConsoleWarn;
+  // eslint-disable-next-line no-console
+  console.error = originalConsoleError;
+});

package/src/arg-parser.ts

@@ -0,0 +1,128 @@
+/**
+ * CLI argument parser for tool parameters.
+ * Converts CLI options to Unity tool parameters.
+ */
+
+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"
+ */
+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>`;
+}