feat(simulator): migrate build_sim to session-aware defaults and concise description

docs(session-management): add Tool Description Policy and update plan example

test: update build_sim and session-management tests for session-aware preflight and description

Author: cameroncooke

docs/session_management_plan.md

@@ -185,7 +185,7 @@ const publicSchemaObject = baseSchemaObject.omit(
 
 export default {
   name: 'build_sim',
-  description: 'Builds an app for a simulator using session defaults (scheme/project/sim).',
+  description: 'Builds an app for an iOS simulator.',
   schema: publicSchemaObject.shape, // what the MCP client sees
   handler: createSessionAwareTool<BuildSimulatorParams>({
     internalSchema: buildSimulatorSchema,
@@ -356,11 +356,26 @@ import plugin, { sessionClearDefaultsLogic } from '../session_clear_defaults.ts'
   - `npm run lint`
   - `npm run test`
 
+### Minimal Changes Policy for Tests (Enforced)
+
+- Only make material, essential edits to tests required by the code change (e.g., new preflight error messages or added/removed fields).
+- Do not change sample input values or defaults in tests (e.g., flipping a boolean like `preferXcodebuild`) unless strictly necessary to validate behavior.
+- Preserve the original intent and coverage of logic-function tests; keep handler vs logic boundaries intact.
+- When session-awareness is added, prefer setting/clearing session defaults around tests rather than altering existing assertions or sample inputs.
+
+### Tool Description Policy (Enforced)
+
+- Keep tool descriptions concise (maximum one short sentence).
+- Do not mention session defaults, setup steps, examples, or parameter relationships in descriptions.
+- Use clear, imperative phrasing (e.g., "Builds an app for an iOS simulator.").
+- Apply consistently across all migrated tools; update any tests that assert `description` to match the concise string only.
+
 ## Commit & Review Protocol (Enforced)
 
 At the end of each numbered step above:
 
 1. Ensure all checks pass: `typecheck`, `lint`, `test`.
+   - Verify tool descriptions comply with the Tool Description Policy (concise, no session-defaults mention).
 2. Stage only the files for that step.
 3. Prepare a concise commit message focused on the “why”.
 4. Request manual review and approval before committing. Do not push.
@@ -408,6 +423,59 @@ Note on commit hooks and selective commits:
   - `session-show-defaults {}`
   - `session-clear-defaults { "all": true }`
 
+## Manual Testing with mcpli (CLI)
+
+The following commands exercise the session workflow end‑to‑end using the built server.
+
+1) Build the server (required after code changes):
+
+```bash
+npm run build
+```
+
+2) Discover a scheme (optional helper):
+
+```bash
+mcpli --raw list-schemes --projectPath "/Volumes/Developer/XcodeBuildMCP/example_projects/iOS/MCPTest.xcodeproj" -- node build/index.js
+```
+
+3) Set the session defaults (project/workspace, scheme, and simulator):
+
+```bash
+mcpli --raw session-set-defaults \
+  --projectPath "/Volumes/Developer/XcodeBuildMCP/example_projects/iOS/MCPTest.xcodeproj" \
+  --scheme MCPTest \
+  --simulatorName "iPhone 16" \
+  -- node build/index.js
+```
+
+4) Verify defaults are stored:
+
+```bash
+mcpli --raw session-show-defaults -- node build/index.js
+```
+
+5) Run a session‑aware tool with zero or minimal args (defaults are merged automatically):
+
+```bash
+# Optionally provide a scratch derived data path and a short timeout
+mcpli --tool-timeout=60 --raw build-sim --derivedDataPath "/tmp/XBMCP_DD" -- node build/index.js
+```
+
+Troubleshooting:
+
+- If you see validation errors like “Missing required session defaults …”, (re)run step 3 with the missing keys.
+- If you see connect ECONNREFUSED or the daemon appears flaky:
+  - Check logs: `mcpli daemon log --since=10m -- node build/index.js`
+  - Restart daemon: `mcpli daemon restart -- node build/index.js`
+  - Clean daemon state: `mcpli daemon clean -- node build/index.js` then `mcpli daemon start -- node build/index.js`
+  - After code changes, always: `npm run build` then `mcpli daemon restart -- node build/index.js`
+
+Notes:
+
+- Public schemas for session‑aware tools intentionally omit session fields (e.g., `scheme`, `projectPath`, `simulatorName`). Provide them once via `session-set-defaults` and then call the tool with zero/minimal flags.
+- Use `--tool-timeout=<seconds>` to cap long‑running builds during manual testing.
+
 ## Next Steps
 
 Would you like me to proceed with Phase 1–3 implementation (store + session tools + middleware), then migrate a first tool (build_sim) and run the test suite?

src/mcp/tools/session-management/__tests__/index.test.ts

@@ -19,7 +19,9 @@ describe('session-management workflow metadata', () => {
     });
 
     it('should have correct description', () => {
-      expect(workflow.description).toBe('Manage session defaults for XcodeBuildMCP tools.');
+      expect(workflow.description).toBe(
+        'Manage session defaults for projectPath/workspacePath, scheme, configuration, simulatorName/simulatorId, deviceId, useLatestOS and arch. These defaults are required by many tools and must be set before attempting to call tools that would depend on these values.',
+      );
     });
 
     it('should have correct platforms array', () => {

src/mcp/tools/simulator/__tests__/build_sim.test.ts

@@ -1,153 +1,64 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { z } from 'zod';
 import { createMockExecutor } from '../../../../test-utils/mock-executors.ts';
+import { sessionStore } from '../../../../utils/session-store.ts';
 
 // Import the plugin and logic function
 import buildSim, { build_simLogic } from '../build_sim.ts';
 
 describe('build_sim tool', () => {
-  // Only clear any remaining mocks if needed
+  beforeEach(() => {
+    sessionStore.clear();
+  });
 
   describe('Export Field Validation (Literal)', () => {
     it('should have correct name', () => {
       expect(buildSim.name).toBe('build_sim');
     });
 
     it('should have correct description', () => {
-      expect(buildSim.description).toBe(
-        "Builds an app from a project or workspace for a specific simulator by UUID or name. Provide exactly one of projectPath or workspacePath, and exactly one of simulatorId or simulatorName. IMPORTANT: Requires either projectPath or workspacePath, plus scheme and either simulatorId or simulatorName. Example: build_sim({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme', simulatorName: 'iPhone 16' })",
-      );
+      expect(buildSim.description).toBe('Builds an app for an iOS simulator.');
     });
 
     it('should have handler function', () => {
       expect(typeof buildSim.handler).toBe('function');
     });
 
-    it('should have correct schema with required and optional fields', () => {
+    it('should have correct public schema (only non-session fields)', () => {
       const schema = z.object(buildSim.schema);
 
-      // Valid inputs - workspace
-      expect(
-        schema.safeParse({
-          workspacePath: '/path/to/workspace',
-          scheme: 'MyScheme',
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(true);
+      // Public schema should allow empty input
+      expect(schema.safeParse({}).success).toBe(true);
 
-      // Valid inputs - project
+      // Valid public inputs
       expect(
         schema.safeParse({
-          projectPath: '/path/to/project.xcodeproj',
-          scheme: 'MyScheme',
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(true);
-
-      expect(
-        schema.safeParse({
-          workspacePath: '/path/to/workspace',
-          scheme: 'MyScheme',
-          simulatorName: 'iPhone 16',
-          configuration: 'Release',
           derivedDataPath: '/path/to/derived',
           extraArgs: ['--verbose'],
-          useLatestOS: true,
           preferXcodebuild: false,
         }).success,
       ).toBe(true);
 
-      // Invalid inputs - missing required fields
-      // Note: simulatorId/simulatorName are optional at schema level, XOR validation at runtime
-      expect(
-        schema.safeParse({
-          workspacePath: '/path/to/workspace',
-          scheme: 'MyScheme',
-        }).success,
-      ).toBe(true); // Schema validation passes, runtime XOR validation would catch missing simulator fields
-
-      expect(
-        schema.safeParse({
-          workspacePath: '/path/to/workspace',
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(false);
-
-      expect(
-        schema.safeParse({
-          scheme: 'MyScheme',
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(true); // Base schema allows both fields optional, XOR validation happens at handler level
-
-      // Invalid types
-      expect(
-        schema.safeParse({
-          workspacePath: 123,
-          scheme: 'MyScheme',
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(false);
-
-      expect(
-        schema.safeParse({
-          workspacePath: '/path/to/workspace',
-          scheme: 123,
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(false);
-
-      expect(
-        schema.safeParse({
-          workspacePath: '/path/to/workspace',
-          scheme: 'MyScheme',
-          simulatorName: 123,
-        }).success,
-      ).toBe(false);
-    });
-
-    it('should validate XOR constraint between projectPath and workspacePath', () => {
-      const schema = z.object(buildSim.schema);
-
-      // Both projectPath and workspacePath provided - should be invalid
-      expect(
-        schema.safeParse({
-          projectPath: '/path/to/project.xcodeproj',
-          workspacePath: '/path/to/workspace',
-          scheme: 'MyScheme',
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(true); // Schema validation passes, but handler validation will catch this
-
-      // Neither provided - should be invalid
-      expect(
-        schema.safeParse({
-          scheme: 'MyScheme',
-          simulatorName: 'iPhone 16',
-        }).success,
-      ).toBe(true); // Schema validation passes, but handler validation will catch this
+      // Invalid types on public inputs
+      expect(schema.safeParse({ derivedDataPath: 123 }).success).toBe(false);
+      expect(schema.safeParse({ extraArgs: [123] }).success).toBe(false);
+      expect(schema.safeParse({ preferXcodebuild: 'yes' }).success).toBe(false);
     });
   });
 
   describe('Parameter Validation', () => {
     it('should handle missing both projectPath and workspacePath', async () => {
-      const mockExecutor = createMockExecutor({ success: true, output: 'Build succeeded' });
-
-      // Since we use XOR validation, this should fail at the handler level
       const result = await buildSim.handler({
         scheme: 'MyScheme',
         simulatorName: 'iPhone 16',
       });
 
       expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('Parameter validation failed');
-      expect(result.content[0].text).toContain('Either projectPath or workspacePath is required');
+      expect(result.content[0].text).toContain('Missing required session defaults');
+      expect(result.content[0].text).toContain('Provide a project or workspace');
     });
 
     it('should handle both projectPath and workspacePath provided', async () => {
-      const mockExecutor = createMockExecutor({ success: true, output: 'Build succeeded' });
-
-      // Since we use XOR validation, this should fail at the handler level
       const result = await buildSim.handler({
         projectPath: '/path/to/project.xcodeproj',
         workspacePath: '/path/to/workspace',
@@ -188,19 +99,14 @@ describe('build_sim tool', () => {
     });
 
     it('should handle missing scheme parameter', async () => {
-      const mockExecutor = createMockExecutor({ success: true, output: 'Build succeeded' });
-
-      // Since we removed manual validation, this test now checks that Zod validation works
-      // by testing the typed tool handler through the default export
       const result = await buildSim.handler({
         workspacePath: '/path/to/workspace',
         simulatorName: 'iPhone 16',
       });
 
       expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('Parameter validation failed');
-      expect(result.content[0].text).toContain('scheme');
-      expect(result.content[0].text).toContain('Required');
+      expect(result.content[0].text).toContain('Missing required session defaults');
+      expect(result.content[0].text).toContain('scheme is required');
     });
 
     it('should handle empty scheme parameter', async () => {
@@ -229,17 +135,14 @@ describe('build_sim tool', () => {
     });
 
     it('should handle missing both simulatorId and simulatorName', async () => {
-      const mockExecutor = createMockExecutor({ success: true, output: 'Build succeeded' });
-
-      // Should fail with XOR validation
       const result = await buildSim.handler({
         workspacePath: '/path/to/workspace',
         scheme: 'MyScheme',
       });
 
       expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('Parameter validation failed');
-      expect(result.content[0].text).toContain('Either simulatorId or simulatorName is required');
+      expect(result.content[0].text).toContain('Missing required session defaults');
+      expect(result.content[0].text).toContain('Provide simulatorId or simulatorName');
     });
 
     it('should handle both simulatorId and simulatorName provided', async () => {

src/mcp/tools/simulator/build_sim.ts

@@ -12,6 +12,7 @@ import { executeXcodeBuildCommand } from '../../../utils/build/index.ts';
 import { ToolResponse, XcodePlatform } from '../../../types/common.ts';
 import type { CommandExecutor } from '../../../utils/execution/index.ts';
 import { getDefaultCommandExecutor } from '../../../utils/execution/index.ts';
+import { createSessionAwareTool } from '../../../utils/typed-tool-factory.ts';
 import { nullifyEmptyStrings } from '../../../utils/schema-helpers.ts';
 
 // Unified schema: XOR between projectPath and workspacePath, and XOR between simulatorId and simulatorName
@@ -135,37 +136,29 @@ export async function build_simLogic(
   return _handleSimulatorBuildLogic(processedParams, executor);
 }
 
+// Public schema = internal minus session-managed fields
+const publicSchemaObject = baseSchemaObject.omit({
+  projectPath: true,
+  workspacePath: true,
+  scheme: true,
+  configuration: true,
+  simulatorId: true,
+  simulatorName: true,
+  useLatestOS: true,
+} as const);
+
 export default {
   name: 'build_sim',
-  description:
-    "Builds an app from a project or workspace for a specific simulator by UUID or name. Provide exactly one of projectPath or workspacePath, and exactly one of simulatorId or simulatorName. IMPORTANT: Requires either projectPath or workspacePath, plus scheme and either simulatorId or simulatorName. Example: build_sim({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme', simulatorName: 'iPhone 16' })",
-  schema: baseSchemaObject.shape, // MCP SDK compatibility
-  handler: async (args: Record<string, unknown>): Promise<ToolResponse> => {
-    try {
-      // Runtime validation with XOR constraints
-      const validatedParams = buildSimulatorSchema.parse(args);
-      return await build_simLogic(validatedParams, getDefaultCommandExecutor());
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        // Format validation errors in a user-friendly way
-        const errorMessages = error.errors.map((e) => {
-          const path = e.path.length > 0 ? `${e.path.join('.')}` : 'root';
-          return `${path}: ${e.message}`;
-        });
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Parameter validation failed. Invalid parameters:\n${errorMessages.join('\n')}`,
-            },
-          ],
-          isError: true,
-        };
-      }
-
-      // Re-throw unexpected errors
-      throw error;
-    }
-  },
+  description: 'Builds an app for an iOS simulator.',
+  schema: publicSchemaObject.shape, // MCP SDK compatibility (public inputs only)
+  handler: createSessionAwareTool<BuildSimulatorParams>({
+    internalSchema: buildSimulatorSchema as unknown as z.ZodType<BuildSimulatorParams>,
+    logicFunction: build_simLogic,
+    getExecutor: getDefaultCommandExecutor,
+    requirements: [
+      { allOf: ['scheme'], message: 'scheme is required' },
+      { oneOf: ['projectPath', 'workspacePath'], message: 'Provide a project or workspace' },
+      { oneOf: ['simulatorId', 'simulatorName'], message: 'Provide simulatorId or simulatorName' },
+    ],
+  }),
 };