uloop-cli 0.44.1

package/src/project-root.ts

@@ -0,0 +1,31 @@
+/**
+ * Unity project root detection utility.
+ * Searches upward from current directory to find Unity project markers.
+ */
+
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+
+/**
+ * Find Unity project root by searching upward from start path.
+ * A Unity project is identified by having both Assets/ and ProjectSettings/ directories.
+ * Returns null if not inside a Unity project.
+ */
+export function findUnityProjectRoot(startPath: string = process.cwd()): string | null {
+  let currentPath = startPath;
+
+  while (true) {
+    const hasAssets = existsSync(join(currentPath, 'Assets'));
+    const hasProjectSettings = existsSync(join(currentPath, 'ProjectSettings'));
+
+    if (hasAssets && hasProjectSettings) {
+      return currentPath;
+    }
+
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      return null;
+    }
+    currentPath = parentPath;
+  }
+}

package/src/simple-framer.ts

@@ -0,0 +1,97 @@
+/**
+ * Simple Content-Length framer for CLI usage.
+ * Minimal implementation without external dependencies.
+ */
+
+const CONTENT_LENGTH_HEADER = 'Content-Length:';
+const HEADER_SEPARATOR = '\r\n\r\n';
+
+export function createFrame(jsonContent: string): string {
+  const contentLength = Buffer.byteLength(jsonContent, 'utf8');
+  return `${CONTENT_LENGTH_HEADER} ${contentLength}${HEADER_SEPARATOR}${jsonContent}`;
+}
+
+export interface FrameParseResult {
+  contentLength: number;
+  headerLength: number;
+  isComplete: boolean;
+}
+
+export function parseFrameFromBuffer(data: Buffer): FrameParseResult {
+  if (!data || data.length === 0) {
+    return { contentLength: -1, headerLength: -1, isComplete: false };
+  }
+
+  const separatorBuffer = Buffer.from(HEADER_SEPARATOR, 'utf8');
+  const separatorIndex = data.indexOf(separatorBuffer);
+
+  if (separatorIndex === -1) {
+    return { contentLength: -1, headerLength: -1, isComplete: false };
+  }
+
+  const headerSection = data.subarray(0, separatorIndex).toString('utf8');
+  const headerLength = separatorIndex + separatorBuffer.length;
+
+  const contentLength = parseContentLength(headerSection);
+  if (contentLength === -1) {
+    return { contentLength: -1, headerLength: -1, isComplete: false };
+  }
+
+  const expectedTotalLength = headerLength + contentLength;
+  const isComplete = data.length >= expectedTotalLength;
+
+  return { contentLength, headerLength, isComplete };
+}
+
+export interface FrameExtractionResult {
+  jsonContent: string | null;
+  remainingData: Buffer;
+}
+
+export function extractFrameFromBuffer(
+  data: Buffer,
+  contentLength: number,
+  headerLength: number,
+): FrameExtractionResult {
+  if (!data || data.length === 0 || contentLength < 0 || headerLength < 0) {
+    return { jsonContent: null, remainingData: data || Buffer.alloc(0) };
+  }
+
+  const expectedTotalLength = headerLength + contentLength;
+
+  if (data.length < expectedTotalLength) {
+    return { jsonContent: null, remainingData: data };
+  }
+
+  const jsonContent = data.subarray(headerLength, headerLength + contentLength).toString('utf8');
+  const remainingData = data.subarray(expectedTotalLength);
+
+  return { jsonContent, remainingData };
+}
+
+function parseContentLength(headerSection: string): number {
+  const lines = headerSection.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+    const lowerLine = trimmedLine.toLowerCase();
+
+    if (lowerLine.startsWith('content-length:')) {
+      const colonIndex = trimmedLine.indexOf(':');
+      if (colonIndex === -1 || colonIndex >= trimmedLine.length - 1) {
+        continue;
+      }
+
+      const valueString = trimmedLine.substring(colonIndex + 1).trim();
+      const parsedValue = parseInt(valueString, 10);
+
+      if (isNaN(parsedValue) || parsedValue < 0) {
+        return -1;
+      }
+
+      return parsedValue;
+    }
+  }
+
+  return -1;
+}

package/src/skills/bundled-skills.ts

@@ -0,0 +1,64 @@
+/**
+ * Bundled skill definitions for uloop CLI.
+ * These skills are embedded at build time via esbuild --loader:.md=text
+ */
+
+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 clearConsoleSkill from './skill-definitions/uloop-clear-console/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 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';
+
+export interface BundledSkill {
+  name: string;
+  dirName: string;
+  content: string;
+}
+
+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-execute-menu-item',
+    dirName: 'uloop-execute-menu-item',
+    content: executeMenuItemSkill,
+  },
+  {
+    name: 'uloop-find-game-objects',
+    dirName: 'uloop-find-game-objects',
+    content: findGameObjectsSkill,
+  },
+  {
+    name: 'uloop-capture-gameview',
+    dirName: 'uloop-capture-gameview',
+    content: captureGameviewSkill,
+  },
+  {
+    name: 'uloop-execute-dynamic-code',
+    dirName: 'uloop-execute-dynamic-code',
+    content: executeDynamicCodeSkill,
+  },
+  {
+    name: 'uloop-get-provider-details',
+    dirName: 'uloop-get-provider-details',
+    content: getProviderDetailsSkill,
+  },
+];
+
+export function getBundledSkillByName(name: string): BundledSkill | undefined {
+  return BUNDLED_SKILLS.find((skill) => skill.name === name);
+}

package/src/skills/markdown.d.ts

@@ -0,0 +1,4 @@
+declare module '*.md' {
+  const content: string;
+  export default content;
+}

package/src/skills/skill-definitions/uloop-capture-gameview/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: uloop-capture-gameview
+description: Capture Unity Game View as PNG via uloop CLI. Use when you need to: (1) Take a screenshot of the current Game View, (2) Capture visual state for debugging or verification, (3) Save game output as an image file.
+---
+
+# uloop capture-gameview
+
+Capture Unity Game View and save as PNG image.
+
+## Usage
+
+```bash
+uloop capture-gameview [--resolution-scale <scale>]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--resolution-scale` | number | `1.0` | Resolution scale (0.1 to 1.0) |
+
+## Examples
+
+```bash
+# Capture at full resolution
+uloop capture-gameview
+
+# Capture at half resolution
+uloop capture-gameview --resolution-scale 0.5
+```
+
+## Output
+
+Returns JSON with file path to the saved PNG image.
+
+## Notes
+
+- Use `uloop focus-window` first if needed
+- Game View must be visible in Unity Editor

package/src/skills/skill-definitions/uloop-clear-console/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: uloop-clear-console
+description: Clear Unity console logs via uloop CLI. Use when you need to: (1) Clear the console before running tests, (2) Start a fresh debugging session, (3) Clean up log output for better readability.
+---
+
+# uloop clear-console
+
+Clear Unity console logs.
+
+## Usage
+
+```bash
+uloop clear-console [--add-confirmation-message]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--add-confirmation-message` | boolean | `false` | Add confirmation message after clearing |
+
+## Examples
+
+```bash
+# Clear console
+uloop clear-console
+
+# Clear with confirmation
+uloop clear-console --add-confirmation-message
+```
+
+## Output
+
+Returns JSON confirming the console was cleared.

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

@@ -0,0 +1,37 @@
+---
+name: uloop-compile
+description: Compile Unity project via uloop CLI. Use when you need to: (1) Verify C# code compiles successfully after editing scripts, (2) Check for compile errors or warnings, (3) Validate script changes before running tests.
+---
+
+# uloop compile
+
+Execute Unity project compilation.
+
+## Usage
+
+```bash
+uloop compile [--force-recompile]
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `--force-recompile` | boolean | Force full recompilation (triggers Domain Reload) |
+
+## Examples
+
+```bash
+# Check compilation
+uloop compile
+
+# Force full recompilation
+uloop compile --force-recompile
+```
+
+## Output
+
+Returns JSON:
+- `Success`: boolean
+- `ErrorCount`: number
+- `WarningCount`: number

package/src/skills/skill-definitions/uloop-execute-dynamic-code/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: uloop-execute-dynamic-code
+description: Execute C# code dynamically in Unity Editor via uloop CLI. Use for editor automation: (1) Prefab/material wiring and AddComponent operations, (2) Reference wiring with SerializedObject, (3) Scene/hierarchy edits and batch operations. NOT for file I/O or script authoring.
+---
+
+# uloop execute-dynamic-code
+
+Execute C# code dynamically in Unity Editor.
+
+## Usage
+
+```bash
+uloop execute-dynamic-code --code '<c# code>'
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `--code` | string | C# code to execute (direct statements, no class wrapper) |
+| `--compile-only` | boolean | Compile without execution |
+| `--auto-qualify-unity-types-once` | boolean | Auto-qualify Unity types |
+
+## Code Format
+
+Write direct statements only (no classes/namespaces/methods). Return is optional.
+
+```csharp
+// Using directives at top are hoisted
+using UnityEngine;
+var x = Mathf.PI;
+return x;
+```
+
+## String Literals (Shell-specific)
+
+| Shell | Method |
+|-------|--------|
+| bash/zsh/MINGW64/Git Bash | `'Debug.Log("Hello!");'` |
+| PowerShell | `'Debug.Log(""Hello!"");'` |
+
+## Allowed Operations
+
+- Prefab/material wiring (PrefabUtility)
+- AddComponent + reference wiring (SerializedObject)
+- Scene/hierarchy edits
+- Inspector modifications
+
+## Forbidden Operations
+
+- System.IO.* (File/Directory/Path)
+- AssetDatabase.CreateFolder / file writes
+- Create/edit .cs/.asmdef files
+
+## Examples
+
+### bash / zsh / MINGW64 / Git Bash
+
+```bash
+uloop execute-dynamic-code --code 'return Selection.activeGameObject?.name;'
+uloop execute-dynamic-code --code 'new GameObject("MyObject");'
+uloop execute-dynamic-code --code 'UnityEngine.Debug.Log("Hello from CLI!");'
+```
+
+### PowerShell
+
+```powershell
+uloop execute-dynamic-code --code 'return Selection.activeGameObject?.name;'
+uloop execute-dynamic-code --code 'new GameObject(""MyObject"");'
+uloop execute-dynamic-code --code 'UnityEngine.Debug.Log(""Hello from CLI!"");'
+```
+
+## Output
+
+Returns JSON with execution result or compile errors.
+
+## Notes
+
+For file/directory operations, use terminal commands instead.

package/src/skills/skill-definitions/uloop-execute-menu-item/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: uloop-execute-menu-item
+description: Execute Unity MenuItem via uloop CLI. Use when you need to: (1) Trigger menu commands programmatically, (2) Automate editor actions (save, build, refresh), (3) Run custom menu items defined in scripts.
+---
+
+# uloop execute-menu-item
+
+Execute Unity MenuItem.
+
+## Usage
+
+```bash
+uloop execute-menu-item --menu-item-path "<path>"
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--menu-item-path` | string | - | Menu item path (e.g., "GameObject/Create Empty") |
+| `--use-reflection-fallback` | boolean | `true` | Use reflection fallback |
+
+## Examples
+
+```bash
+# Create empty GameObject
+uloop execute-menu-item --menu-item-path "GameObject/Create Empty"
+
+# Save scene
+uloop execute-menu-item --menu-item-path "File/Save"
+
+# Open project settings
+uloop execute-menu-item --menu-item-path "Edit/Project Settings..."
+```
+
+## Output
+
+Returns JSON with execution result.
+
+## Notes
+
+- Use `uloop get-menu-items` to discover available menu paths
+- Some menu items may require specific context or selection

package/src/skills/skill-definitions/uloop-find-game-objects/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: uloop-find-game-objects
+description: Find GameObjects with search criteria via uloop CLI. Use when you need to: (1) Locate GameObjects by name pattern, (2) Find objects by tag or layer, (3) Search for objects with specific component types.
+---
+
+# uloop find-game-objects
+
+Find GameObjects with search criteria.
+
+## Usage
+
+```bash
+uloop find-game-objects [options]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--name-pattern` | string | - | Name pattern to search |
+| `--search-mode` | string | `Contains` | Search mode: `Exact`, `Path`, `Regex`, `Contains` |
+| `--required-components` | array | - | Required components |
+| `--tag` | string | - | Tag filter |
+| `--layer` | string | - | Layer filter |
+| `--max-results` | integer | `20` | Maximum number of results |
+| `--include-inactive` | boolean | `false` | Include inactive GameObjects |
+
+## Examples
+
+```bash
+# Find by name
+uloop find-game-objects --name-pattern "Player"
+
+# Find with component
+uloop find-game-objects --required-components Rigidbody
+
+# Find by tag
+uloop find-game-objects --tag "Enemy"
+
+# Regex search
+uloop find-game-objects --name-pattern "UI_.*" --search-mode Regex
+```
+
+## Output
+
+Returns JSON array of matching GameObjects with paths and components.

package/src/skills/skill-definitions/uloop-focus-window/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: uloop-focus-window
+description: Bring Unity Editor window to front via uloop CLI. Use when you need to: (1) Focus Unity Editor before capturing screenshots, (2) Ensure Unity window is visible for visual checks, (3) Bring Unity to foreground for user interaction.
+---
+
+# uloop focus-window
+
+Bring Unity Editor window to front.
+
+## Usage
+
+```bash
+uloop focus-window
+```
+
+## Parameters
+
+None.
+
+## Examples
+
+```bash
+# Focus Unity Editor
+uloop focus-window
+```
+
+## Output
+
+Returns JSON confirming the window was focused.
+
+## Notes
+
+- Useful before `uloop capture-gameview` to ensure Game View is visible
+- Brings the main Unity Editor window to the foreground

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

@@ -0,0 +1,44 @@
+---
+name: uloop-get-hierarchy
+description: Get Unity Hierarchy structure via uloop CLI. Use when you need to: (1) Inspect scene structure and GameObject tree, (2) Find GameObjects and their parent-child relationships, (3) Check component attachments on objects.
+---
+
+# uloop get-hierarchy
+
+Get Unity Hierarchy structure.
+
+## Usage
+
+```bash
+uloop get-hierarchy [options]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--root-path` | string | - | Root GameObject path to start from |
+| `--max-depth` | integer | `-1` | Maximum depth (-1 for unlimited) |
+| `--include-components` | boolean | `true` | Include component information |
+| `--include-inactive` | boolean | `true` | Include inactive GameObjects |
+| `--include-paths` | boolean | `false` | Include full path information |
+
+## Examples
+
+```bash
+# Get entire hierarchy
+uloop get-hierarchy
+
+# Get hierarchy from specific root
+uloop get-hierarchy --root-path "Canvas/UI"
+
+# Limit depth
+uloop get-hierarchy --max-depth 2
+
+# Without components
+uloop get-hierarchy --include-components false
+```
+
+## Output
+
+Returns JSON with hierarchical structure of GameObjects and their components.

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

@@ -0,0 +1,45 @@
+---
+name: uloop-get-logs
+description: Retrieve Unity Console logs via uloop CLI. Use when you need to: (1) Check for errors or warnings after operations, (2) Debug runtime issues in Unity Editor, (3) Investigate unexpected behavior or exceptions.
+---
+
+# uloop get-logs
+
+Retrieve logs from Unity Console.
+
+## Usage
+
+```bash
+uloop get-logs [options]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--log-type` | string | `All` | Log type filter: `Error`, `Warning`, `Log`, `All` |
+| `--max-count` | integer | `100` | Maximum number of logs to retrieve |
+| `--search-text` | string | - | Text to search within logs |
+| `--include-stack-trace` | boolean | `true` | Include stack trace in output |
+| `--use-regex` | boolean | `false` | Use regex for search |
+| `--search-in-stack-trace` | boolean | `false` | Search within stack trace |
+
+## Examples
+
+```bash
+# Get all logs
+uloop get-logs
+
+# Get only errors
+uloop get-logs --log-type Error
+
+# Search for specific text
+uloop get-logs --search-text "NullReference"
+
+# Regex search
+uloop get-logs --search-text "Missing.*Component" --use-regex
+```
+
+## Output
+
+Returns JSON array of log entries with message, type, and optional stack trace.

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

@@ -0,0 +1,44 @@
+---
+name: uloop-get-menu-items
+description: Retrieve Unity MenuItems via uloop CLI. Use when you need to: (1) Discover available menu commands in Unity Editor, (2) Find menu paths for automation, (3) Prepare for executing menu items programmatically.
+---
+
+# uloop get-menu-items
+
+Retrieve Unity MenuItems.
+
+## Usage
+
+```bash
+uloop get-menu-items [options]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--filter-text` | string | - | Filter text |
+| `--filter-type` | string | `contains` | Filter type: `contains`, `exact`, `startswith` |
+| `--max-count` | integer | `200` | Maximum number of items |
+| `--include-validation` | boolean | `false` | Include validation functions |
+
+## Examples
+
+```bash
+# List all menu items
+uloop get-menu-items
+
+# Filter by text
+uloop get-menu-items --filter-text "GameObject"
+
+# Exact match
+uloop get-menu-items --filter-text "File/Save" --filter-type exact
+```
+
+## Output
+
+Returns JSON array of menu items with paths and metadata.
+
+## Notes
+
+Use with `uloop execute-menu-item` to run discovered menu commands.

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

@@ -0,0 +1,34 @@
+---
+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.
+---
+
+# uloop get-project-info
+
+Get detailed Unity project information.
+
+## Usage
+
+```bash
+uloop get-project-info
+```
+
+## Parameters
+
+None.
+
+## Examples
+
+```bash
+# Get project info
+uloop get-project-info
+```
+
+## Output
+
+Returns JSON with project information:
+- Unity version
+- Project name
+- Platform settings
+- Build target
+- Other project metadata