uloop-cli 0.45.2 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.45.2",
+  "version": "0.47.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -9,7 +9,8 @@
   },
   "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",
+    "generate-skills": "npx tsx scripts/generate-bundled-skills.ts",
+    "build": "npm run generate-skills && 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",
@@ -41,12 +42,15 @@
     "provenance": true
   },
   "dependencies": {
-    "commander": "^14.0.2"
+    "commander": "^14.0.2",
+    "semver": "^7.7.3"
   },
   "devDependencies": {
     "@eslint/js": "9.39.2",
+    "tsx": "4.19.0",
     "@types/jest": "30.0.0",
     "@types/node": "25.0.2",
+    "@types/semver": "^7.7.1",
     "esbuild": "0.27.1",
     "eslint": "9.39.2",
     "eslint-config-prettier": "^10.1.8",

package/scripts/generate-bundled-skills.ts

@@ -0,0 +1,159 @@
+/**
+ * Auto-generates bundled-skills.ts from skill-definitions directory.
+ * Scans all SKILL.md files and generates import statements and BUNDLED_SKILLS array.
+ * Skills with `internal: true` in frontmatter are excluded from generation.
+ *
+ * Usage: npx tsx scripts/generate-bundled-skills.ts
+ */
+
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const SKILL_DEFINITIONS_DIR = join(__dirname, '../src/skills/skill-definitions');
+const OUTPUT_FILE = join(__dirname, '../src/skills/bundled-skills.ts');
+
+interface SkillMetadata {
+  dirName: string;
+  name: string;
+  isInternal: boolean;
+}
+
+function parseFrontmatter(content: string): Record<string, string | boolean> {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    return {};
+  }
+
+  const frontmatter: Record<string, string | boolean> = {};
+  const lines = frontmatterMatch[1].split('\n');
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+
+    if (value === 'true') {
+      frontmatter[key] = true;
+    } else if (value === 'false') {
+      frontmatter[key] = false;
+    } else {
+      frontmatter[key] = value;
+    }
+  }
+
+  return frontmatter;
+}
+
+function getSkillMetadata(dirName: string): SkillMetadata | null {
+  const skillPath = join(SKILL_DEFINITIONS_DIR, dirName, 'SKILL.md');
+
+  if (!existsSync(skillPath)) {
+    return null;
+  }
+
+  const content = readFileSync(skillPath, 'utf-8');
+  const frontmatter = parseFrontmatter(content);
+
+  const name = typeof frontmatter.name === 'string' ? frontmatter.name : dirName;
+  const isInternal = frontmatter.internal === true;
+
+  return { dirName, name, isInternal };
+}
+
+function toVariableName(dirName: string): string {
+  return dirName
+    .replace(/^uloop-/, '')
+    .replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+    .concat('Skill');
+}
+
+function generateBundledSkillsFile(skills: SkillMetadata[]): string {
+  const imports = skills
+    .map((skill) => {
+      const varName = toVariableName(skill.dirName);
+      return `import ${varName} from './skill-definitions/${skill.dirName}/SKILL.md';`;
+    })
+    .join('\n');
+
+  const entries = skills
+    .map((skill) => {
+      const varName = toVariableName(skill.dirName);
+      return `  {
+    name: '${skill.name}',
+    dirName: '${skill.dirName}',
+    content: ${varName},
+  },`;
+    })
+    .join('\n');
+
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
+ * Generated by: scripts/generate-bundled-skills.ts
+ *
+ * This file is automatically generated from skill-definitions directory.
+ * To add a new skill, create a new directory in skill-definitions with a SKILL.md file.
+ * To exclude a skill from bundling, add \`internal: true\` to its frontmatter.
+ */
+
+${imports}
+
+export interface BundledSkill {
+  name: string;
+  dirName: string;
+  content: string;
+}
+
+export const BUNDLED_SKILLS: BundledSkill[] = [
+${entries}
+];
+
+export function getBundledSkillByName(name: string): BundledSkill | undefined {
+  return BUNDLED_SKILLS.find((skill) => skill.name === name);
+}
+`;
+}
+
+function main(): void {
+  const dirs = readdirSync(SKILL_DEFINITIONS_DIR, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => dirent.name)
+    .sort();
+
+  const allSkills: SkillMetadata[] = [];
+  const internalSkills: string[] = [];
+
+  for (const dirName of dirs) {
+    const metadata = getSkillMetadata(dirName);
+    if (metadata === null) {
+      console.warn(`Warning: No SKILL.md found in ${dirName}, skipping`);
+      continue;
+    }
+
+    if (metadata.isInternal) {
+      internalSkills.push(metadata.name);
+      continue;
+    }
+
+    allSkills.push(metadata);
+  }
+
+  const output = generateBundledSkillsFile(allSkills);
+  writeFileSync(OUTPUT_FILE, output, 'utf-8');
+
+  console.log(`Generated ${OUTPUT_FILE}`);
+  console.log(`  - Included: ${allSkills.length} skills`);
+  if (internalSkills.length > 0) {
+    console.log(`  - Excluded (internal): ${internalSkills.join(', ')}`);
+  }
+}
+
+main();
+

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.45.2",
+  "version": "0.47.0",
   "tools": [
     {
       "name": "compile",

package/src/execute-tool.ts

@@ -10,6 +10,7 @@
 import * as readline from 'readline';
 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 { saveToolsCache, getCacheFilePath, ToolsCache, ToolDefinition } from './tool-cache.js';
@@ -70,6 +71,52 @@ function isRetryableError(error: unknown): boolean {
   return message.includes('ECONNREFUSED') || message === 'UNITY_NO_RESPONSE';
 }
 
+/**
+ * Compare two semantic versions safely.
+ * Returns true if v1 < v2, false otherwise.
+ * Falls back to string comparison if versions are invalid.
+ */
+function isVersionOlder(v1: string, v2: string): boolean {
+  const parsed1 = semver.valid(v1);
+  const parsed2 = semver.valid(v2);
+
+  if (parsed1 && parsed2) {
+    return semver.lt(parsed1, parsed2);
+  }
+
+  return v1 < v2;
+}
+
+/**
+ * Print version mismatch warning to stderr.
+ * Does not block execution - just warns the user.
+ */
+function printVersionWarning(cliVersion: string, serverVersion: string): void {
+  const isCliOlder = isVersionOlder(cliVersion, serverVersion);
+  const updateCommand = isCliOlder
+    ? `npm install -g uloop-cli@${serverVersion}`
+    : `Update uLoopMCP package to ${cliVersion} via Unity Package Manager`;
+
+  console.error('\x1b[33m⚠️ Version mismatch detected!\x1b[0m');
+  console.error(`   uloop-cli version:    ${cliVersion}`);
+  console.error(`   uloop server version: ${serverVersion}`);
+  console.error('');
+  console.error('   This may cause unexpected behavior or errors.');
+  console.error('');
+  console.error(`   ${isCliOlder ? 'To update CLI:' : 'To update server:'} ${updateCommand}`);
+  console.error('');
+}
+
+/**
+ * Check server version from response and print warning if mismatched.
+ */
+function checkServerVersion(result: Record<string, unknown>): void {
+  const serverVersion = result['ULoopServerVersion'] as string | undefined;
+  if (serverVersion && serverVersion !== VERSION) {
+    printVersionWarning(VERSION, serverVersion);
+  }
+}
+
 /**
  * Check if Unity is in a busy state (compiling, reloading, or server starting).
  * Throws an error with appropriate message if busy.
@@ -123,7 +170,7 @@ export async function executeToolCommand(
       await client.connect();
 
       spinner.update(`Executing ${toolName}...`);
-      const result = await client.sendRequest(toolName, params);
+      const result = await client.sendRequest<Record<string, unknown>>(toolName, params);
 
       if (result === undefined || result === null) {
         throw new Error('UNITY_NO_RESPONSE');
@@ -132,6 +179,10 @@ export async function executeToolCommand(
       // Success - stop spinner and output result
       spinner.stop();
       restoreStdin();
+
+      // Check server version and warn if mismatched
+      checkServerVersion(result);
+
       console.log(JSON.stringify(result, null, 2));
       return;
     } catch (error) {

package/src/skills/bundled-skills.ts

@@ -1,21 +1,26 @@
 /**
- * Bundled skill definitions for uloop CLI.
- * These skills are embedded at build time via esbuild --loader:.md=text
+ * AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
+ * Generated by: scripts/generate-bundled-skills.ts
+ *
+ * This file is automatically generated from skill-definitions directory.
+ * To add a new skill, create a new directory in skill-definitions with a SKILL.md file.
+ * To exclude a skill from bundling, add `internal: true` to its frontmatter.
  */
 
-import compileSkill from './skill-definitions/uloop-compile/SKILL.md';
-import getLogsSkill from './skill-definitions/uloop-get-logs/SKILL.md';
-import runTestsSkill from './skill-definitions/uloop-run-tests/SKILL.md';
+import captureGameviewSkill from './skill-definitions/uloop-capture-gameview/SKILL.md';
 import clearConsoleSkill from './skill-definitions/uloop-clear-console/SKILL.md';
+import compileSkill from './skill-definitions/uloop-compile/SKILL.md';
+import controlPlayModeSkill from './skill-definitions/uloop-control-play-mode/SKILL.md';
+import executeDynamicCodeSkill from './skill-definitions/uloop-execute-dynamic-code/SKILL.md';
+import executeMenuItemSkill from './skill-definitions/uloop-execute-menu-item/SKILL.md';
+import findGameObjectsSkill from './skill-definitions/uloop-find-game-objects/SKILL.md';
 import focusWindowSkill from './skill-definitions/uloop-focus-window/SKILL.md';
 import getHierarchySkill from './skill-definitions/uloop-get-hierarchy/SKILL.md';
-import unitySearchSkill from './skill-definitions/uloop-unity-search/SKILL.md';
+import getLogsSkill from './skill-definitions/uloop-get-logs/SKILL.md';
 import getMenuItemsSkill from './skill-definitions/uloop-get-menu-items/SKILL.md';
-import executeMenuItemSkill from './skill-definitions/uloop-execute-menu-item/SKILL.md';
-import findGameObjectsSkill from './skill-definitions/uloop-find-game-objects/SKILL.md';
-import captureGameviewSkill from './skill-definitions/uloop-capture-gameview/SKILL.md';
-import executeDynamicCodeSkill from './skill-definitions/uloop-execute-dynamic-code/SKILL.md';
 import getProviderDetailsSkill from './skill-definitions/uloop-get-provider-details/SKILL.md';
+import runTestsSkill from './skill-definitions/uloop-run-tests/SKILL.md';
+import unitySearchSkill from './skill-definitions/uloop-unity-search/SKILL.md';
 
 export interface BundledSkill {
   name: string;
@@ -24,14 +29,31 @@ export interface BundledSkill {
 }
 
 export const BUNDLED_SKILLS: BundledSkill[] = [
-  { name: 'uloop-compile', dirName: 'uloop-compile', content: compileSkill },
-  { name: 'uloop-get-logs', dirName: 'uloop-get-logs', content: getLogsSkill },
-  { name: 'uloop-run-tests', dirName: 'uloop-run-tests', content: runTestsSkill },
-  { name: 'uloop-clear-console', dirName: 'uloop-clear-console', content: clearConsoleSkill },
-  { name: 'uloop-focus-window', dirName: 'uloop-focus-window', content: focusWindowSkill },
-  { name: 'uloop-get-hierarchy', dirName: 'uloop-get-hierarchy', content: getHierarchySkill },
-  { name: 'uloop-unity-search', dirName: 'uloop-unity-search', content: unitySearchSkill },
-  { name: 'uloop-get-menu-items', dirName: 'uloop-get-menu-items', content: getMenuItemsSkill },
+  {
+    name: 'uloop-capture-gameview',
+    dirName: 'uloop-capture-gameview',
+    content: captureGameviewSkill,
+  },
+  {
+    name: 'uloop-clear-console',
+    dirName: 'uloop-clear-console',
+    content: clearConsoleSkill,
+  },
+  {
+    name: 'uloop-compile',
+    dirName: 'uloop-compile',
+    content: compileSkill,
+  },
+  {
+    name: 'uloop-control-play-mode',
+    dirName: 'uloop-control-play-mode',
+    content: controlPlayModeSkill,
+  },
+  {
+    name: 'uloop-execute-dynamic-code',
+    dirName: 'uloop-execute-dynamic-code',
+    content: executeDynamicCodeSkill,
+  },
   {
     name: 'uloop-execute-menu-item',
     dirName: 'uloop-execute-menu-item',
@@ -43,20 +65,40 @@ export const BUNDLED_SKILLS: BundledSkill[] = [
     content: findGameObjectsSkill,
   },
   {
-    name: 'uloop-capture-gameview',
-    dirName: 'uloop-capture-gameview',
-    content: captureGameviewSkill,
+    name: 'uloop-focus-window',
+    dirName: 'uloop-focus-window',
+    content: focusWindowSkill,
   },
   {
-    name: 'uloop-execute-dynamic-code',
-    dirName: 'uloop-execute-dynamic-code',
-    content: executeDynamicCodeSkill,
+    name: 'uloop-get-hierarchy',
+    dirName: 'uloop-get-hierarchy',
+    content: getHierarchySkill,
+  },
+  {
+    name: 'uloop-get-logs',
+    dirName: 'uloop-get-logs',
+    content: getLogsSkill,
+  },
+  {
+    name: 'uloop-get-menu-items',
+    dirName: 'uloop-get-menu-items',
+    content: getMenuItemsSkill,
   },
   {
     name: 'uloop-get-provider-details',
     dirName: 'uloop-get-provider-details',
     content: getProviderDetailsSkill,
   },
+  {
+    name: 'uloop-run-tests',
+    dirName: 'uloop-run-tests',
+    content: runTestsSkill,
+  },
+  {
+    name: 'uloop-unity-search',
+    dirName: 'uloop-unity-search',
+    content: unitySearchSkill,
+  },
 ];
 
 export function getBundledSkillByName(name: string): BundledSkill | undefined {

package/src/skills/skill-definitions/uloop-control-play-mode/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: uloop-control-play-mode
+description: Control Unity Editor play mode via uloop CLI. Use when you need to: (1) Start play mode for testing, (2) Stop play mode after testing, (3) Pause play mode for debugging.
+---
+
+# uloop control-play-mode
+
+Control Unity Editor play mode (play/stop/pause).
+
+## Usage
+
+```bash
+uloop control-play-mode [options]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--action` | string | `Play` | Action to perform: `Play`, `Stop`, `Pause` |
+
+## Examples
+
+```bash
+# Start play mode
+uloop control-play-mode --action Play
+
+# Stop play mode
+uloop control-play-mode --action Stop
+
+# Pause play mode
+uloop control-play-mode --action Pause
+```
+
+## Output
+
+Returns JSON with the current play mode state:
+- `IsPlaying`: Whether Unity is currently in play mode
+- `IsPaused`: Whether play mode is paused
+- `Message`: Description of the action performed
+
+## Notes
+
+- Play action starts the game in the Unity Editor (also resumes from pause)
+- Stop action exits play mode and returns to edit mode
+- Pause action pauses the game while remaining in play mode
+- Useful for automated testing workflows
+

package/src/skills/skill-definitions/uloop-get-project-info/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: uloop-get-project-info
 description: Get Unity project information via uloop CLI. Use when you need to: (1) Check Unity Editor version, (2) Get project settings and platform info, (3) Retrieve project metadata for diagnostics.
+internal: true
 ---
 
 # uloop get-project-info

package/src/skills/skill-definitions/uloop-get-version/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: uloop-get-version
 description: Get uLoopMCP version information via uloop CLI. Use when you need to: (1) Check uLoopMCP package version, (2) Verify installation is working correctly, (3) Troubleshoot version compatibility issues.
+internal: true
 ---
 
 # uloop get-version

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