uloop-cli 0.67.4 → 0.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uloop-cli",
-  "version": "0.67.4",
+  "version": "0.68.0",
   "//version": "x-release-please-version",
   "description": "CLI tool for Unity Editor communication via uLoopMCP",
   "main": "dist/cli.bundle.cjs",
@@ -48,7 +48,7 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/jest": "30.0.0",
-    "@types/node": "25.3.1",
+    "@types/node": "25.3.2",
     "@types/semver": "7.7.1",
     "esbuild": "0.27.3",
     "eslint": "10.0.2",
@@ -63,6 +63,6 @@
     "typescript-eslint": "8.56.1"
   },
   "overrides": {
-    "minimatch": "10.2.2"
+    "minimatch": "10.2.4"
   }
 }

package/src/__tests__/tool-settings-loader.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Unit tests for tool-settings-loader.ts
+ *
+ * Tests pure functions for loading and filtering disabled tools.
+ * Uses temporary directories to avoid affecting real project settings.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+// Mock findUnityProjectRoot before importing the module
+let mockProjectRoot: string | null = null;
+
+jest.mock('../project-root.js', () => ({
+  findUnityProjectRoot: (): string | null => mockProjectRoot,
+}));
+
+// Import after mocking
+import { loadDisabledTools, isToolEnabled, filterEnabledTools } from '../tool-settings-loader.js';
+import type { ToolDefinition } from '../tool-cache.js';
+
+describe('tool-settings-loader', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `uloop-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(join(testDir, '.uloop'), { recursive: true });
+    mockProjectRoot = testDir;
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+    mockProjectRoot = null;
+  });
+
+  // ── loadDisabledTools ──────────────────────────────────────────
+
+  describe('loadDisabledTools', () => {
+    it('should return disabled tools from valid settings file', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['compile', 'get-logs'] }),
+      );
+
+      const result: string[] = loadDisabledTools();
+
+      expect(result).toEqual(['compile', 'get-logs']);
+    });
+
+    it('should return empty array when file does not exist', () => {
+      const result: string[] = loadDisabledTools();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array when project root is null', () => {
+      mockProjectRoot = null;
+
+      const result: string[] = loadDisabledTools();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array for invalid JSON', () => {
+      writeFileSync(join(testDir, '.uloop', 'settings.tools.json'), '{invalid json}');
+
+      const result: string[] = loadDisabledTools();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array for empty file', () => {
+      writeFileSync(join(testDir, '.uloop', 'settings.tools.json'), '');
+
+      const result: string[] = loadDisabledTools();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array when disabledTools is not an array', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: 'not-an-array' }),
+      );
+
+      const result: string[] = loadDisabledTools();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array when disabledTools key is missing', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ other: 'data' }),
+      );
+
+      const result: string[] = loadDisabledTools();
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  // ── isToolEnabled ──────────────────────────────────────────────
+
+  describe('isToolEnabled', () => {
+    it('should return false for a disabled tool', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['compile'] }),
+      );
+
+      expect(isToolEnabled('compile')).toBe(false);
+    });
+
+    it('should return true for an enabled tool', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['compile'] }),
+      );
+
+      expect(isToolEnabled('get-logs')).toBe(true);
+    });
+
+    it('should return true when no settings file exists', () => {
+      expect(isToolEnabled('compile')).toBe(true);
+    });
+  });
+
+  // ── filterEnabledTools ─────────────────────────────────────────
+
+  describe('filterEnabledTools', () => {
+    const mockTools: ToolDefinition[] = [
+      {
+        name: 'compile',
+        description: 'Compile',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'get-logs',
+        description: 'Get logs',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'clear-console',
+        description: 'Clear',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ];
+
+    it('should filter out disabled tools', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['compile', 'clear-console'] }),
+      );
+
+      const result: ToolDefinition[] = filterEnabledTools(mockTools);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('get-logs');
+    });
+
+    it('should return all tools when none are disabled', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: [] }),
+      );
+
+      const result: ToolDefinition[] = filterEnabledTools(mockTools);
+
+      expect(result).toHaveLength(3);
+    });
+
+    it('should return all tools when settings file does not exist', () => {
+      const result: ToolDefinition[] = filterEnabledTools(mockTools);
+
+      expect(result).toHaveLength(3);
+    });
+  });
+
+  // ── projectPath override ────────────────────────────────────────
+
+  describe('projectPath override', () => {
+    let otherDir: string;
+
+    beforeEach(() => {
+      otherDir = join(tmpdir(), `uloop-other-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      mkdirSync(join(otherDir, '.uloop'), { recursive: true });
+    });
+
+    afterEach(() => {
+      rmSync(otherDir, { recursive: true, force: true });
+    });
+
+    it('should load settings from projectPath instead of cwd project root', () => {
+      writeFileSync(
+        join(otherDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['get-logs'] }),
+      );
+
+      const result: string[] = loadDisabledTools(otherDir);
+
+      expect(result).toEqual(['get-logs']);
+    });
+
+    it('should ignore cwd project root when projectPath is provided', () => {
+      writeFileSync(
+        join(testDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['compile'] }),
+      );
+      writeFileSync(
+        join(otherDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['get-logs'] }),
+      );
+
+      expect(loadDisabledTools(otherDir)).toEqual(['get-logs']);
+      expect(loadDisabledTools()).toEqual(['compile']);
+    });
+
+    it('should pass projectPath through isToolEnabled', () => {
+      writeFileSync(
+        join(otherDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['compile'] }),
+      );
+
+      expect(isToolEnabled('compile', otherDir)).toBe(false);
+      expect(isToolEnabled('get-logs', otherDir)).toBe(true);
+    });
+
+    it('should pass projectPath through filterEnabledTools', () => {
+      const mockTools: ToolDefinition[] = [
+        {
+          name: 'compile',
+          description: 'Compile',
+          inputSchema: { type: 'object', properties: {} },
+        },
+        {
+          name: 'get-logs',
+          description: 'Get logs',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ];
+      writeFileSync(
+        join(otherDir, '.uloop', 'settings.tools.json'),
+        JSON.stringify({ disabledTools: ['compile'] }),
+      );
+
+      const result: ToolDefinition[] = filterEnabledTools(mockTools, otherDir);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('get-logs');
+    });
+
+    it('should return empty array when projectPath has no settings file', () => {
+      const result: string[] = loadDisabledTools(otherDir);
+
+      expect(result).toEqual([]);
+    });
+  });
+});

package/src/cli.ts

@@ -35,6 +35,7 @@ import { registerFocusWindowCommand } from './commands/focus-window.js';
 import { VERSION } from './version.js';
 import { findUnityProjectRoot } from './project-root.js';
 import { validateProjectPath } from './port-resolver.js';
+import { filterEnabledTools, isToolEnabled } from './tool-settings-loader.js';
 
 interface CliOptions extends GlobalOptions {
   [key: string]: unknown;
@@ -312,6 +313,11 @@ function isConnectionError(message: string): boolean {
   return message.includes('ECONNREFUSED') || message.includes('EADDRNOTAVAIL');
 }
 
+function printToolDisabledError(cmdName: string): void {
+  console.error(`\x1b[33mTool '${cmdName}' is disabled.\x1b[0m`);
+  console.error('You can enable it in Unity: Window > uLoop > Tool Settings');
+}
+
 function printConnectionError(): void {
   console.error('\x1b[31mError: Cannot connect to Unity.\x1b[0m');
   console.error('Make sure Unity Editor is open and uLoopMCP server is running.');
@@ -707,10 +713,15 @@ function handleCompletion(install: boolean, shellOverride?: string): void {
  */
 function handleCompletionOptions(): boolean {
   const args = process.argv.slice(2);
+  const projectPath: string | undefined = extractSyncGlobalOptions(args).projectPath;
 
   if (args.includes('--list-commands')) {
     const tools = loadToolsCache();
-    const allCommands = [...BUILTIN_COMMANDS, ...tools.tools.map((t) => t.name)];
+    // Only filter disabled tools when --project-path is explicitly provided;
+    // without it, loadDisabledTools would trigger findUnityProjectRoot() scanning
+    const enabledTools: ToolDefinition[] =
+      projectPath !== undefined ? filterEnabledTools(tools.tools, projectPath) : tools.tools;
+    const allCommands = [...BUILTIN_COMMANDS, ...enabledTools.map((t) => t.name)];
     console.log(allCommands.join('\n'));
     return true;
   }
@@ -718,7 +729,7 @@ function handleCompletionOptions(): boolean {
   const listOptionsIdx = args.indexOf('--list-options');
   if (listOptionsIdx !== -1 && args[listOptionsIdx + 1]) {
     const cmdName = args[listOptionsIdx + 1];
-    listOptionsForCommand(cmdName);
+    listOptionsForCommand(cmdName, projectPath);
     return true;
   }
 
@@ -728,15 +739,20 @@ function handleCompletionOptions(): boolean {
 /**
  * List options for a specific command.
  */
-function listOptionsForCommand(cmdName: string): void {
+function listOptionsForCommand(cmdName: string, projectPath?: string): void {
   // Built-in commands have no tool-specific options
   if (BUILTIN_COMMANDS.includes(cmdName as (typeof BUILTIN_COMMANDS)[number])) {
     return;
   }
 
   // Tool commands - only output tool-specific options
+  // Only filter disabled tools when --project-path is explicitly provided;
+  // without it, loadDisabledTools would trigger findUnityProjectRoot() scanning
   const tools = loadToolsCache();
-  const tool = tools.tools.find((t) => t.name === cmdName);
+  const tool: ToolDefinition | undefined =
+    projectPath !== undefined
+      ? filterEnabledTools(tools.tools, projectPath).find((t) => t.name === cmdName)
+      : tools.tools.find((t) => t.name === cmdName);
   if (!tool) {
     return;
   }
@@ -753,12 +769,12 @@ function listOptionsForCommand(cmdName: string): void {
 /**
  * Check if a command exists in the current program.
  */
-function commandExists(cmdName: string): boolean {
+function commandExists(cmdName: string, projectPath?: string): boolean {
   if (BUILTIN_COMMANDS.includes(cmdName as (typeof BUILTIN_COMMANDS)[number])) {
     return true;
   }
   const tools = loadToolsCache();
-  return tools.tools.some((t) => t.name === cmdName);
+  return filterEnabledTools(tools.tools, projectPath).some((t) => t.name === cmdName);
 }
 
 function shouldSkipAutoSync(cmdName: string | undefined, args: string[]): boolean {
@@ -822,7 +838,13 @@ async function main(): Promise<void> {
 
   if (skipProjectDetection) {
     const defaultTools = getDefaultTools();
-    for (const tool of defaultTools.tools) {
+    // Only filter disabled tools when --project-path is explicitly provided;
+    // without it, filterEnabledTools would trigger findUnityProjectRoot() scanning
+    const tools: ToolDefinition[] =
+      syncGlobalOptions.projectPath !== undefined
+        ? filterEnabledTools(defaultTools.tools, syncGlobalOptions.projectPath)
+        : defaultTools.tools;
+    for (const tool of tools) {
       registerToolCommand(tool);
     }
     program.parse();
@@ -855,16 +877,22 @@ async function main(): Promise<void> {
 
   // Register tool commands from cache (after potential auto-sync)
   const toolsCache = loadToolsCache();
-  for (const tool of toolsCache.tools) {
+  const projectPath: string | undefined = syncGlobalOptions.projectPath;
+  for (const tool of filterEnabledTools(toolsCache.tools, projectPath)) {
     registerToolCommand(tool);
   }
 
-  if (cmdName && !commandExists(cmdName)) {
+  if (cmdName && !commandExists(cmdName, projectPath)) {
+    if (!isToolEnabled(cmdName, projectPath)) {
+      printToolDisabledError(cmdName);
+      process.exit(1);
+    }
+
     console.log(`\x1b[33mUnknown command '${cmdName}'. Syncing tools from Unity...\x1b[0m`);
     try {
       await syncTools(syncGlobalOptions);
       const newCache = loadToolsCache();
-      const tool = newCache.tools.find((t) => t.name === cmdName);
+      const tool = filterEnabledTools(newCache.tools, projectPath).find((t) => t.name === cmdName);
       if (tool) {
         registerToolCommand(tool);
         console.log(`\x1b[32m✓ Found '${cmdName}' after sync.\x1b[0m\n`);

package/src/default-tools.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.67.4",
+  "version": "0.68.0",
   "tools": [
     {
       "name": "compile",
@@ -343,8 +343,8 @@
       }
     },
     {
-      "name": "capture-window",
-      "description": "Capture Unity EditorWindow and save as PNG",
+      "name": "screenshot",
+      "description": "Take a screenshot of Unity EditorWindow and save as PNG",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -367,6 +367,11 @@
               "contains"
             ],
             "default": "exact"
+          },
+          "OutputDirectory": {
+            "type": "string",
+            "description": "Output directory path for saving screenshots. When empty, uses default path (.uloop/outputs/Screenshots/). Accepts absolute paths.",
+            "default": ""
           }
         }
       }
@@ -392,33 +397,6 @@
         }
       }
     },
-    {
-      "name": "get-provider-details",
-      "description": "Get Unity Search provider details",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "ProviderId": {
-            "type": "string",
-            "description": "Specific provider ID"
-          },
-          "ActiveOnly": {
-            "type": "boolean",
-            "description": "Only active providers"
-          },
-          "IncludeDescriptions": {
-            "type": "boolean",
-            "description": "Include descriptions",
-            "default": true
-          },
-          "SortByPriority": {
-            "type": "boolean",
-            "description": "Sort by priority",
-            "default": true
-          }
-        }
-      }
-    },
     {
       "name": "get-project-info",
       "description": "Get Unity project information",

package/src/skills/deprecated-skills.ts

@@ -6,4 +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
 ];

package/src/skills/skills-manager.ts

@@ -13,6 +13,7 @@ import { homedir } from 'os';
 import { TargetConfig } from './target-config.js';
 import { findUnityProjectRoot, getUnityProjectStatus } from '../project-root.js';
 import { DEPRECATED_SKILLS } from './deprecated-skills.js';
+import { loadDisabledTools } from '../tool-settings-loader.js';
 
 export type SkillStatus = 'installed' | 'not_installed' | 'outdated';
 
@@ -25,6 +26,7 @@ export interface SkillInfo {
 
 export interface SkillDefinition {
   name: string;
+  toolName?: string;
   dirName: string;
   content: string;
   sourcePath: string;
@@ -145,13 +147,13 @@ export function getSkillStatus(
 }
 
 export function parseFrontmatter(content: string): Record<string, string | boolean> {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!frontmatterMatch) {
     return {};
   }
 
   const frontmatterMap = new Map<string, string | boolean>();
-  const lines = frontmatterMatch[1].split('\n');
+  const lines = frontmatterMatch[1].split(/\r?\n/);
 
   for (const line of lines) {
     const colonIndex = line.indexOf(':');
@@ -239,10 +241,13 @@ function scanEditorFolderForSkills(
         }
 
         const name = typeof frontmatter.name === 'string' ? frontmatter.name : entry.name;
+        const toolName =
+          typeof frontmatter.toolName === 'string' ? frontmatter.toolName : undefined;
         const additionalFiles = collectSkillFolderFiles(skillDir);
 
         skills.push({
           name,
+          toolName,
           dirName: name,
           content,
           sourcePath: skillMdPath,
@@ -399,11 +404,19 @@ export function installAllSkills(target: TargetConfig, global: boolean): Install
     }
   }
 
+  // Global installs ignore project-local tool settings
+  const disabledTools: string[] = global ? [] : loadDisabledTools();
+
   const allSkills = collectAllSkills();
   const projectSkills = allSkills.filter((skill) => skill.sourceType === 'project');
   const nonProjectSkills = allSkills.filter((skill) => skill.sourceType !== 'project');
 
   for (const skill of allSkills) {
+    if (isSkillDisabledByToolSettings(skill, disabledTools)) {
+      uninstallSkill(skill, target, global);
+      continue;
+    }
+
     const status = getSkillStatus(skill, target, global);
 
     if (status === 'not_installed') {
@@ -422,6 +435,19 @@ export function installAllSkills(target: TargetConfig, global: boolean): Install
   return result;
 }
 
+function isSkillDisabledByToolSettings(skill: SkillDefinition, disabledTools: string[]): boolean {
+  if (disabledTools.length === 0) {
+    return false;
+  }
+
+  const toolName: string | null =
+    skill.toolName ?? (skill.name.startsWith('uloop-') ? skill.name.slice('uloop-'.length) : null);
+  if (toolName === null) {
+    return false;
+  }
+  return disabledTools.includes(toolName);
+}
+
 export interface UninstallResult {
   removed: number;
   notFound: number;

package/src/tool-settings-loader.ts

@@ -0,0 +1,74 @@
+/**
+ * Loads tool toggle settings from .uloop/settings.tools.json.
+ * Used by CLI to filter out disabled tools from help and command registration.
+ */
+
+// File paths are constructed from Unity project root, not from untrusted user input
+/* eslint-disable security/detect-non-literal-fs-filename */
+
+import { readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { findUnityProjectRoot } from './project-root.js';
+import type { ToolDefinition } from './tool-cache.js';
+
+const ULOOP_DIR = '.uloop';
+const TOOL_SETTINGS_FILE = 'settings.tools.json';
+
+interface ToolSettingsData {
+  disabledTools: string[];
+}
+
+export function loadDisabledTools(projectPath?: string): string[] {
+  const projectRoot: string | null =
+    projectPath !== undefined ? resolve(projectPath) : findUnityProjectRoot();
+  if (projectRoot === null) {
+    return [];
+  }
+
+  const settingsPath: string = join(projectRoot, ULOOP_DIR, TOOL_SETTINGS_FILE);
+
+  let content: string;
+  try {
+    content = readFileSync(settingsPath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  if (!content.trim()) {
+    return [];
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return [];
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) {
+    return [];
+  }
+
+  const data = parsed as ToolSettingsData;
+  if (!Array.isArray(data.disabledTools)) {
+    return [];
+  }
+
+  return data.disabledTools;
+}
+
+export function isToolEnabled(toolName: string, projectPath?: string): boolean {
+  const disabledTools: string[] = loadDisabledTools(projectPath);
+  return !disabledTools.includes(toolName);
+}
+
+export function filterEnabledTools(
+  tools: ToolDefinition[],
+  projectPath?: string,
+): ToolDefinition[] {
+  const disabledTools: string[] = loadDisabledTools(projectPath);
+  if (disabledTools.length === 0) {
+    return tools;
+  }
+  return tools.filter((tool) => !disabledTools.includes(tool.name));
+}

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