uloop-cli 0.56.0 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -41,23 +41,24 @@
     "provenance": true
   },
   "dependencies": {
-    "commander": "^14.0.2",
-    "semver": "^7.7.3"
+    "commander": "14.0.2",
+    "launch-unity": "0.12.0",
+    "semver": "7.7.3"
   },
   "devDependencies": {
     "@eslint/js": "9.39.2",
-    "tsx": "4.21.0",
     "@types/jest": "30.0.0",
     "@types/node": "25.0.2",
-    "@types/semver": "^7.7.1",
+    "@types/semver": "7.7.1",
     "esbuild": "0.27.1",
     "eslint": "9.39.2",
-    "eslint-config-prettier": "^10.1.8",
+    "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",
+    "tsx": "4.21.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.49.0"
   }

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

@@ -482,6 +482,46 @@ describe('CLI E2E Tests (requires running Unity)', () => {
     });
   });
 
+  describe('launch', () => {
+    it('should display launch command help', () => {
+      const { stdout, exitCode } = runCli('launch --help');
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Launch Unity project');
+      expect(stdout).toContain('--restart');
+      expect(stdout).toContain('--platform');
+      expect(stdout).toContain('--max-depth');
+      expect(stdout).toContain('--add-unity-hub');
+      expect(stdout).toContain('--favorite');
+    });
+
+    it('should detect already running Unity and focus window', () => {
+      // Unity is already running for this test suite, so launch should detect it
+      const { stdout, exitCode } = runCli(`launch "${UNITY_PROJECT_ROOT}"`);
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Unity process already running');
+    });
+
+    it('should fail gracefully when project not found', () => {
+      const { stdout, stderr, exitCode } = runCli('launch /nonexistent/path/to/project');
+
+      expect(exitCode).not.toBe(0);
+      // Error message should mention project not found or version file not found
+      const output = stderr || stdout;
+      expect(output).toMatch(/not found|does not appear to be a Unity project/i);
+    });
+
+    it('should search for Unity project from current directory', () => {
+      // This test runs from Unity project root, so it should find the project
+      const { stdout, exitCode } = runCli('launch');
+
+      expect(exitCode).toBe(0);
+      // Should either find and focus existing Unity or report no Unity found
+      expect(stdout).toMatch(/Unity process already running|Selected project/);
+    });
+  });
+
   // Domain Reload tests must run last to avoid affecting other tests
   describe('compile --force-recompile (Domain Reload)', () => {
     it('should support --force-recompile option', () => {

package/src/cli.ts

@@ -29,6 +29,7 @@ import {
 } from './tool-cache.js';
 import { pascalToKebabCase } from './arg-parser.js';
 import { registerSkillsCommand } from './skills/skills-command.js';
+import { registerLaunchCommand } from './commands/launch.js';
 import { VERSION } from './version.js';
 import { findUnityProjectRoot } from './project-root.js';
 
@@ -36,7 +37,15 @@ interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
 }
 
-const BUILTIN_COMMANDS = ['list', 'sync', 'completion', 'update', 'fix', 'skills'] as const;
+const BUILTIN_COMMANDS = [
+  'list',
+  'sync',
+  'completion',
+  'update',
+  'fix',
+  'skills',
+  'launch',
+] as const;
 
 const program = new Command();
 
@@ -94,6 +103,9 @@ program
 // Register skills subcommand
 registerSkillsCommand(program);
 
+// Register launch subcommand
+registerLaunchCommand(program);
+
 /**
  * Register a tool as a CLI command dynamically.
  */

package/src/commands/launch.ts

@@ -0,0 +1,125 @@
+/**
+ * CLI command for launching Unity projects.
+ * Integrates launch-unity library into uloop CLI.
+ */
+
+// CLI commands output to console by design
+/* eslint-disable no-console */
+
+import { Command } from 'commander';
+import { resolve } from 'path';
+
+import {
+  findUnityProjectBfs,
+  getUnityVersion,
+  launch,
+  findRunningUnityProcess,
+  focusUnityProcess,
+  killRunningUnity,
+  handleStaleLockfile,
+  ensureProjectEntryAndUpdate,
+  updateLastModifiedIfExists,
+  LaunchResolvedOptions,
+} from 'launch-unity';
+
+interface LaunchCommandOptions {
+  restart?: boolean;
+  platform?: string;
+  maxDepth?: string;
+  addUnityHub?: boolean;
+  favorite?: boolean;
+}
+
+export function registerLaunchCommand(program: Command): void {
+  program
+    .command('launch')
+    .description('Launch Unity project with matching Editor version')
+    .argument('[project-path]', 'Path to Unity project')
+    .option('-r, --restart', 'Kill running Unity and restart')
+    .option('-p, --platform <platform>', 'Build target (e.g., Android, iOS)')
+    .option('--max-depth <n>', 'Search depth when project-path is omitted', '3')
+    .option('-a, --add-unity-hub', 'Add to Unity Hub (does not launch)')
+    .option('-f, --favorite', 'Add to Unity Hub as favorite (does not launch)')
+    .action(async (projectPath: string | undefined, options: LaunchCommandOptions) => {
+      await runLaunchCommand(projectPath, options);
+    });
+}
+
+function parseMaxDepth(value: string | undefined): number {
+  if (value === undefined) {
+    return 3;
+  }
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    console.error(`Error: Invalid --max-depth value: "${value}". Must be an integer.`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+async function runLaunchCommand(
+  projectPath: string | undefined,
+  options: LaunchCommandOptions,
+): Promise<void> {
+  const maxDepth = parseMaxDepth(options.maxDepth);
+
+  let resolvedProjectPath: string | undefined = projectPath ? resolve(projectPath) : undefined;
+
+  if (!resolvedProjectPath) {
+    const searchRoot = process.cwd();
+    const depthInfo = maxDepth === -1 ? 'unlimited' : String(maxDepth);
+    console.log(
+      `No project-path provided. Searching under ${searchRoot} (max-depth: ${depthInfo})...`,
+    );
+    const found = findUnityProjectBfs(searchRoot, maxDepth);
+    if (!found) {
+      console.error(`Error: Unity project not found under ${searchRoot}.`);
+      process.exit(1);
+    }
+    console.log(`Selected project: ${found}`);
+    resolvedProjectPath = found;
+  }
+
+  const unityVersion = getUnityVersion(resolvedProjectPath);
+
+  const unityHubOnlyMode = options.addUnityHub === true || options.favorite === true;
+  if (unityHubOnlyMode) {
+    console.log(`Detected Unity version: ${unityVersion}`);
+    console.log(`Project Path: ${resolvedProjectPath}`);
+    const now = new Date();
+    await ensureProjectEntryAndUpdate(
+      resolvedProjectPath,
+      unityVersion,
+      now,
+      options.favorite === true,
+    );
+    console.log('Unity Hub entry updated.');
+    return;
+  }
+
+  if (options.restart === true) {
+    await killRunningUnity(resolvedProjectPath);
+  } else {
+    const runningProcess = await findRunningUnityProcess(resolvedProjectPath);
+    if (runningProcess) {
+      console.log(
+        `Unity process already running for project: ${resolvedProjectPath} (PID: ${runningProcess.pid})`,
+      );
+      await focusUnityProcess(runningProcess.pid);
+      return;
+    }
+  }
+
+  await handleStaleLockfile(resolvedProjectPath);
+
+  const resolved: LaunchResolvedOptions = {
+    projectPath: resolvedProjectPath,
+    platform: options.platform,
+    unityArgs: [],
+    unityVersion,
+  };
+  launch(resolved);
+
+  const now = new Date();
+  await updateLastModifiedIfExists(resolvedProjectPath, now);
+}

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.56.0",
+  "version": "0.57.0",
   "tools": [
     {
       "name": "compile",

package/src/skills/skill-definitions/cli-only/uloop-launch/Skill/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: uloop-launch
+description: "Launch Unity project with matching Editor version via uloop CLI. Use when you need to: (1) Open a Unity project with the correct Editor version, (2) Restart Unity to apply changes, (3) Switch build target when launching."
+---
+
+# uloop launch
+
+Launch Unity Editor with the correct version for a project.
+
+## Usage
+
+```bash
+uloop launch [project-path] [options]
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `project-path` | string | Path to Unity project (optional, searches current directory if omitted) |
+| `-r, --restart` | boolean | Kill running Unity and restart |
+| `-p, --platform <P>` | string | Build target (e.g., StandaloneOSX, Android, iOS) |
+| `--max-depth <N>` | number | Search depth when project-path is omitted (default: 3, -1 for unlimited) |
+| `-a, --add-unity-hub` | boolean | Add to Unity Hub only (does not launch) |
+| `-f, --favorite` | boolean | Add to Unity Hub as favorite (does not launch) |
+
+## Examples
+
+```bash
+# Search for Unity project in current directory and launch
+uloop launch
+
+# Launch specific project
+uloop launch /path/to/project
+
+# Restart Unity (kill existing and relaunch)
+uloop launch -r
+
+# Launch with build target
+uloop launch -p Android
+
+# Add project to Unity Hub without launching
+uloop launch -a
+```
+
+## Output
+
+- Prints detected Unity version
+- Prints project path
+- If Unity is already running, focuses the existing window
+- If launching, opens Unity in background

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