feat(simulator): migrate simulator tools to session defaults

docs/TOOLS.md

@@ -69,7 +69,7 @@ XcodeBuildMCP provides 61 tools organized into 12 workflow groups for comprehens
 ### Simulator Management (`simulator-management`)
 **Purpose**: Tools for managing simulators from booting, opening simulators, listing simulators, stopping simulators, erasing simulator content and settings, and setting simulator environment options like location, network, statusbar and appearance. (5 tools)
 
-- `erase_sims` - Erases simulator content and settings. Provide exactly one of: simulatorUdid or all=true. Optional: shutdownFirst to shut down before erasing.
+- `erase_sims` - Erases simulator content and settings for a specific simulator. Requires simulatorUdid. Optional: shutdownFirst to shut down before erasing.
 - `reset_sim_location` - Resets the simulator's location to default.
 - `set_sim_appearance` - Sets the appearance mode (dark/light) of an iOS simulator.
 - `set_sim_location` - Sets a custom GPS location for the simulator.

docs/session-aware-migration-todo.md

@@ -41,14 +41,14 @@ Reference: `docs/session_management_plan.md`
 - [x] `src/mcp/tools/simulator/record_sim_video.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
 
 ## Simulator Management
-- [ ] `src/mcp/tools/simulator-management/erase_sims.ts` — session defaults: `simulatorId` (covers `simulatorUdid`).
-- [ ] `src/mcp/tools/simulator-management/set_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator-management/reset_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator-management/set_sim_appearance.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
-- [ ] `src/mcp/tools/simulator-management/sim_statusbar.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/erase_sims.ts` — session defaults: `simulatorId` (covers `simulatorUdid`).
+- [x] `src/mcp/tools/simulator-management/set_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/reset_sim_location.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/set_sim_appearance.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/simulator-management/sim_statusbar.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
 
 ## Simulator Logging
-- [ ] `src/mcp/tools/logging/start_sim_log_cap.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
+- [x] `src/mcp/tools/logging/start_sim_log_cap.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).
 
 ## AXe UI Testing Tools
 - [ ] `src/mcp/tools/ui-testing/button.ts` — session defaults: `simulatorId` (hydrate `simulatorUuid`).

example_projects/iOS_Calculator/.gitignore

@@ -0,0 +1,7 @@
+
+# xcode-build-server files
+buildServer.json
+.compile
+
+# Local build artifacts
+.build/

src/mcp/tools/logging/__tests__/start_sim_log_cap.test.ts

@@ -1,7 +1,7 @@
 /**
  * Tests for start_sim_log_cap plugin
  */
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { z } from 'zod';
 import plugin, { start_sim_log_capLogic } from '../start_sim_log_cap.ts';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
@@ -33,51 +33,30 @@ describe('start_sim_log_cap plugin', () => {
 
     it('should validate schema with valid parameters', () => {
       const schema = z.object(plugin.schema);
-      expect(
-        schema.safeParse({ simulatorUuid: 'test-uuid', bundleId: 'com.example.app' }).success,
-      ).toBe(true);
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: true,
-        }).success,
-      ).toBe(true);
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: false,
-        }).success,
-      ).toBe(true);
+      expect(schema.safeParse({ bundleId: 'com.example.app' }).success).toBe(true);
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: true }).success).toBe(
+        true,
+      );
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: false }).success).toBe(
+        true,
+      );
     });
 
     it('should reject invalid schema parameters', () => {
       const schema = z.object(plugin.schema);
-      expect(schema.safeParse({ simulatorUuid: null, bundleId: 'com.example.app' }).success).toBe(
+      expect(schema.safeParse({ bundleId: null }).success).toBe(false);
+      expect(schema.safeParse({ captureConsole: true }).success).toBe(false);
+      expect(schema.safeParse({}).success).toBe(false);
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: 'yes' }).success).toBe(
         false,
       );
-      expect(
-        schema.safeParse({ simulatorUuid: undefined, bundleId: 'com.example.app' }).success,
-      ).toBe(false);
-      expect(schema.safeParse({ simulatorUuid: 'test-uuid', bundleId: null }).success).toBe(false);
-      expect(schema.safeParse({ simulatorUuid: 'test-uuid', bundleId: undefined }).success).toBe(
+      expect(schema.safeParse({ bundleId: 'com.example.app', captureConsole: 123 }).success).toBe(
         false,
       );
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: 'yes',
-        }).success,
-      ).toBe(false);
-      expect(
-        schema.safeParse({
-          simulatorUuid: 'test-uuid',
-          bundleId: 'com.example.app',
-          captureConsole: 123,
-        }).success,
-      ).toBe(false);
+
+      const withSimId = schema.safeParse({ simulatorId: 'test-uuid', bundleId: 'com.example.app' });
+      expect(withSimId.success).toBe(true);
+      expect('simulatorId' in (withSimId.data as any)).toBe(false);
     });
   });
 
@@ -98,7 +77,7 @@ describe('start_sim_log_cap plugin', () => {
 
       const result = await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
         },
         mockExecutor,
@@ -122,7 +101,7 @@ describe('start_sim_log_cap plugin', () => {
 
       const result = await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
         },
         mockExecutor,
@@ -148,7 +127,7 @@ describe('start_sim_log_cap plugin', () => {
 
       const result = await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
           captureConsole: true,
         },
@@ -208,7 +187,7 @@ describe('start_sim_log_cap plugin', () => {
 
       await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
           captureConsole: true,
         },
@@ -277,7 +256,7 @@ describe('start_sim_log_cap plugin', () => {
 
       await start_sim_log_capLogic(
         {
-          simulatorUuid: 'test-uuid',
+          simulatorId: 'test-uuid',
           bundleId: 'com.example.app',
           captureConsole: false,
         },

src/mcp/tools/logging/start_sim_log_cap.ts

@@ -8,12 +8,13 @@ import { z } from 'zod';
 import { startLogCapture } from '../../../utils/log-capture/index.ts';
 import { CommandExecutor, getDefaultCommandExecutor } from '../../../utils/command.ts';
 import { ToolResponse, createTextContent } from '../../../types/common.ts';
-import { createTypedTool } from '../../../utils/typed-tool-factory.ts';
+import { createSessionAwareTool } from '../../../utils/typed-tool-factory.ts';
 
 // Define schema as ZodObject
 const startSimLogCapSchema = z.object({
-  simulatorUuid: z
+  simulatorId: z
     .string()
+    .uuid()
     .describe('UUID of the simulator to capture logs from (obtained from list_simulators).'),
   bundleId: z.string().describe('Bundle identifier of the app to capture logs for.'),
   captureConsole: z
@@ -30,11 +31,15 @@ export async function start_sim_log_capLogic(
   _executor: CommandExecutor = getDefaultCommandExecutor(),
   logCaptureFunction: typeof startLogCapture = startLogCapture,
 ): Promise<ToolResponse> {
-  const paramsWithDefaults = {
-    ...params,
-    captureConsole: params.captureConsole ?? false,
-  };
-  const { sessionId, error } = await logCaptureFunction(paramsWithDefaults, _executor);
+  const captureConsole = params.captureConsole ?? false;
+  const { sessionId, error } = await logCaptureFunction(
+    {
+      simulatorUuid: params.simulatorId,
+      bundleId: params.bundleId,
+      captureConsole,
+    },
+    _executor,
+  );
   if (error) {
     return {
       content: [createTextContent(`Error starting log capture: ${error}`)],
@@ -44,16 +49,23 @@ export async function start_sim_log_capLogic(
   return {
     content: [
       createTextContent(
-        `Log capture started successfully. Session ID: ${sessionId}.\n\n${paramsWithDefaults.captureConsole ? 'Note: Your app was relaunched to capture console output.' : 'Note: Only structured logs are being captured.'}\n\nNext Steps:\n1.  Interact with your simulator and app.\n2.  Use 'stop_sim_log_cap' with session ID '${sessionId}' to stop capture and retrieve logs.`,
+        `Log capture started successfully. Session ID: ${sessionId}.\n\n${captureConsole ? 'Note: Your app was relaunched to capture console output.' : 'Note: Only structured logs are being captured.'}\n\nNext Steps:\n1.  Interact with your simulator and app.\n2.  Use 'stop_sim_log_cap' with session ID '${sessionId}' to stop capture and retrieve logs.`,
       ),
     ],
   };
 }
 
+const publicSchemaObject = startSimLogCapSchema.omit({ simulatorId: true } as const).strict();
+
 export default {
   name: 'start_sim_log_cap',
   description:
     'Starts capturing logs from a specified simulator. Returns a session ID. By default, captures only structured logs.',
-  schema: startSimLogCapSchema.shape, // MCP SDK compatibility
-  handler: createTypedTool(startSimLogCapSchema, start_sim_log_capLogic, getDefaultCommandExecutor),
+  schema: publicSchemaObject.shape, // MCP SDK compatibility
+  handler: createSessionAwareTool<StartSimLogCapParams>({
+    internalSchema: startSimLogCapSchema as unknown as z.ZodType<StartSimLogCapParams>,
+    logicFunction: start_sim_log_capLogic,
+    getExecutor: getDefaultCommandExecutor,
+    requirements: [{ allOf: ['simulatorId'], message: 'simulatorId is required' }],
+  }),
 };

src/mcp/tools/simulator-management/__tests__/erase_sims.test.ts

@@ -3,15 +3,14 @@ import { z } from 'zod';
 import eraseSims, { erase_simsLogic } from '../erase_sims.ts';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
 
-describe('erase_sims tool (UDID or ALL only)', () => {
+describe('erase_sims tool (single simulator)', () => {
   describe('Export Field Validation (Literal)', () => {
     it('should have correct name', () => {
       expect(eraseSims.name).toBe('erase_sims');
     });
 
     it('should have correct description', () => {
-      expect(eraseSims.description).toContain('Provide exactly one of: simulatorUdid or all=true');
-      expect(eraseSims.description).toContain('shutdownFirst');
+      expect(eraseSims.description).toBe('Erases a simulator by UDID.');
     });
 
     it('should have handler function', () => {
@@ -20,27 +19,23 @@ describe('erase_sims tool (UDID or ALL only)', () => {
 
     it('should validate schema fields (shape only)', () => {
       const schema = z.object(eraseSims.schema);
-      // Valid
-      expect(
-        schema.safeParse({ simulatorUdid: '123e4567-e89b-12d3-a456-426614174000' }).success,
-      ).toBe(true);
-      expect(schema.safeParse({ all: true }).success).toBe(true);
-      // Shape-level schema does not enforce selection rules; handler validation covers that.
+      expect(schema.safeParse({ shutdownFirst: true }).success).toBe(true);
+      expect(schema.safeParse({}).success).toBe(true);
     });
   });
 
   describe('Single mode', () => {
     it('erases a simulator successfully', async () => {
       const mock = createMockExecutor({ success: true, output: 'OK' });
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1' }, mock);
+      const res = await erase_simsLogic({ simulatorId: 'UD1' }, mock);
       expect(res).toEqual({
         content: [{ type: 'text', text: 'Successfully erased simulator UD1' }],
       });
     });
 
     it('returns failure when erase fails', async () => {
       const mock = createMockExecutor({ success: false, error: 'Booted device' });
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1' }, mock);
+      const res = await erase_simsLogic({ simulatorId: 'UD1' }, mock);
       expect(res).toEqual({
         content: [{ type: 'text', text: 'Failed to erase simulator: Booted device' }],
       });
@@ -50,7 +45,7 @@ describe('erase_sims tool (UDID or ALL only)', () => {
       const bootedError =
         'An error was encountered processing the command (domain=com.apple.CoreSimulator.SimError, code=405):\nUnable to erase contents and settings in current state: Booted\n';
       const mock = createMockExecutor({ success: false, error: bootedError });
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1' }, mock);
+      const res = await erase_simsLogic({ simulatorId: 'UD1' }, mock);
       expect((res.content?.[1] as any).text).toContain('Tool hint');
       expect((res.content?.[1] as any).text).toContain('shutdownFirst: true');
     });
@@ -61,7 +56,7 @@ describe('erase_sims tool (UDID or ALL only)', () => {
         calls.push(cmd);
         return { success: true, output: 'OK', error: '', process: { pid: 1 } as any };
       };
-      const res = await erase_simsLogic({ simulatorUdid: 'UD1', shutdownFirst: true }, exec as any);
+      const res = await erase_simsLogic({ simulatorId: 'UD1', shutdownFirst: true }, exec as any);
       expect(calls).toEqual([
         ['xcrun', 'simctl', 'shutdown', 'UD1'],
         ['xcrun', 'simctl', 'erase', 'UD1'],
@@ -71,46 +66,4 @@ describe('erase_sims tool (UDID or ALL only)', () => {
       });
     });
   });
-
-  describe('All mode', () => {
-    it('erases all simulators successfully', async () => {
-      const exec = createMockExecutor({ success: true, output: 'OK' });
-      const res = await erase_simsLogic({ all: true }, exec);
-      expect(res).toEqual({
-        content: [{ type: 'text', text: 'Successfully erased all simulators' }],
-      });
-    });
-
-    it('returns failure when erase all fails', async () => {
-      const exec = createMockExecutor({ success: false, error: 'Denied' });
-      const res = await erase_simsLogic({ all: true }, exec);
-      expect(res).toEqual({
-        content: [{ type: 'text', text: 'Failed to erase all simulators: Denied' }],
-      });
-    });
-
-    it('performs shutdown all when shutdownFirst=true', async () => {
-      const calls: any[] = [];
-      const exec = async (cmd: string[]) => {
-        calls.push(cmd);
-        return { success: true, output: 'OK', error: '', process: { pid: 1 } as any };
-      };
-      const res = await erase_simsLogic({ all: true, shutdownFirst: true }, exec as any);
-      expect(calls).toEqual([
-        ['xcrun', 'simctl', 'shutdown', 'all'],
-        ['xcrun', 'simctl', 'erase', 'all'],
-      ]);
-      expect(res).toEqual({
-        content: [{ type: 'text', text: 'Successfully erased all simulators' }],
-      });
-    });
-
-    it('adds tool hint on booted error without shutdownFirst (all mode)', async () => {
-      const bootedError = 'Unable to erase contents and settings in current state: Booted';
-      const exec = createMockExecutor({ success: false, error: bootedError });
-      const res = await erase_simsLogic({ all: true }, exec);
-      expect((res.content?.[1] as any).text).toContain('Tool hint');
-      expect((res.content?.[1] as any).text).toContain('shutdownFirst: true');
-    });
-  });
 });