fix(runtime): Merge dynamic next-step params into templates

Apply dynamic next-step params even when manifest templates already define\nparams so scaffold follow-up actions resolve placeholders correctly.\n\nAlign testing docs and pattern checks with the canonical policy:\nuse executor/filesystem DI for external boundaries and allow Vitest\nmocking for internal collaborators.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

docs/dev/ARCHITECTURE.md

@@ -418,7 +418,7 @@ Not all parts are required for every tool. For example, `swift_package_build` ha
 
 ### Testing Principles
 
-XcodeBuildMCP uses a strict **Dependency Injection (DI)** pattern for testing, which completely bans the use of traditional mocking libraries like Vitest's `vi.mock` or `vi.fn`. This ensures that tests are robust, maintainable, and verify the actual integration between components.
+XcodeBuildMCP uses a **Dependency Injection (DI)** pattern for testing external boundaries (command execution, filesystem, and other side effects). Vitest mocking libraries (`vi.mock`, `vi.fn`, etc.) are acceptable for internal collaborators when needed. This keeps tests robust while preserving deterministic behavior at external boundaries.
 
 For detailed guidelines, see the [Testing Guide](TESTING.md).
 

docs/dev/CODE_QUALITY.md

@@ -61,9 +61,9 @@ XcodeBuildMCP enforces several architectural patterns that cannot be expressed t
 - Logic functions accepting `executor?: CommandExecutor` parameter
 
 ❌ **Forbidden**:
-- Direct use of `vi.mock()`, `vi.fn()`, or any Vitest mocking
 - Direct calls to `execSync`, `spawn`, or `exec` in production code
 - Testing handler functions directly
+- Real external side effects in unit tests (xcodebuild/xcrun/filesystem writes outside mocks)
 
 ### 2. Handler Signature Compliance
 
@@ -145,7 +145,7 @@ The pattern checker enforces XcodeBuildMCP-specific architectural rules:
 node scripts/check-code-patterns.js
 
 # Check specific pattern type
-node scripts/check-code-patterns.js --pattern=vitest
+node scripts/check-code-patterns.js
 node scripts/check-code-patterns.js --pattern=execsync
 node scripts/check-code-patterns.js --pattern=handler
 node scripts/check-code-patterns.js --pattern=handler-testing
@@ -172,12 +172,11 @@ npm run tools:all
 
 The pattern checker identifies the following violations:
 
-### 1. Vitest Mocking Violations
-
-**What**: Any use of Vitest mocking functions
-**Why**: Breaks dependency injection architecture
-**Fix**: Use `createMockExecutor()` instead
+### 1. External-Boundary Mocking Violations
 
+**What**: Tests that mock external side effects without injected executors/filesystem dependencies
+**Why**: Breaks deterministic external-boundary testing
+**Fix**: Use `createMockExecutor()` / `createMockFileSystemExecutor()` for external dependencies
 ### 2. ExecSync Violations
 
 **What**: Direct use of Node.js child_process functions in production code
@@ -251,7 +250,7 @@ node scripts/check-code-patterns.js  # Check architectural compliance
 ### 3. Writing Tests
 
 1. Import the logic function, not the default export
-2. Use `createMockExecutor()` for mocking
+2. Use `createMockExecutor()` / `createMockFileSystemExecutor()` for external side effects
 3. Test three dimensions: validation, command generation, output processing
 4. Never test handlers directly
 

docs/dev/CONTRIBUTING.md

@@ -270,8 +270,8 @@ Before making changes, please familiarize yourself with:
 All contributions must adhere to the testing standards outlined in the [**XcodeBuildMCP Plugin Testing Guidelines (TESTING.md)**](TESTING.md). This is the canonical source of truth for all testing practices.
 
 **Key Principles (Summary):**
-- **No Vitest Mocking**: All forms of `vi.mock`, `vi.fn`, `vi.spyOn`, etc., are strictly forbidden.
-- **Dependency Injection**: All external dependencies (command execution, file system access) must be injected into tool logic functions using the `CommandExecutor` and `FileSystemExecutor` patterns.
+- **Dependency Injection for External Boundaries**: All external dependencies (command execution, file system access) must be injected into tool logic functions using the `CommandExecutor` and `FileSystemExecutor` patterns.
+- **Internal Mocking Is Allowed**: Vitest mocking (`vi.mock`, `vi.fn`, `vi.spyOn`, etc.) is acceptable for internal modules/collaborators.
 - **Test Production Code**: Tests must import and execute the actual tool logic, not mock implementations.
 - **Comprehensive Coverage**: Tests must cover input validation, command generation, and output processing.
 

docs/dev/TESTING.md

@@ -18,53 +18,40 @@ This document provides comprehensive testing guidelines for XcodeBuildMCP plugin
 
 ## Testing Philosophy
 
-### 🚨 CRITICAL: No Vitest Mocking Allowed
-
-### ABSOLUTE RULE: ALL VITEST MOCKING IS COMPLETELY BANNED
-
-### FORBIDDEN PATTERNS (will cause immediate test failure):
-
-#### Vitest Mocking (COMPLETELY BANNED):
-- `vi.mock()` - BANNED
-- `vi.fn()` - BANNED  
-- `vi.mocked()` - BANNED
-- `vi.spyOn()` - BANNED
-- `.mockResolvedValue()` - BANNED
-- `.mockRejectedValue()` - BANNED
-- `.mockReturnValue()` - BANNED
-- `.mockImplementation()` - BANNED
-- `.toHaveBeenCalled()` - BANNED
-- `.toHaveBeenCalledWith()` - BANNED
-- `MockedFunction` type - BANNED
-
-#### Manual Mock Implementations (BANNED - use our utilities instead):
-- `const mockExecutor = async (...) => { ... }` - Use `createMockExecutor()` instead
-- `const mockFsDeps = { readFile: async () => ... }` - Use `createMockFileSystemExecutor()` instead
-- `const mockServer = { ... }` - Refactor to use dependency injection pattern
-- Any manual async function implementations for mocking behavior
-
-### ONLY ALLOWED MOCKING:
-- `createMockExecutor({ success: true, output: 'result' })` - command execution
-- `createMockFileSystemExecutor({ readFile: async () => 'content' })` - file system operations
+### 🚨 CRITICAL: External Dependency Mocking Rules
+
+### ABSOLUTE RULE: External side effects must use dependency injection utilities
+
+### Use dependency-injection mocks for EXTERNAL dependencies:
+- `createMockExecutor()` / `createNoopExecutor()` for command execution (`xcrun`, `xcodebuild`, AXe, etc.)
+- `createMockFileSystemExecutor()` / `createNoopFileSystemExecutor()` for file system interactions
+
+### Internal mocking guidance:
+- Vitest mocking (`vi.fn`, `vi.mock`, `vi.spyOn`, `.mockResolvedValue`, etc.) is allowed for internal modules and in-memory collaborators
+- Prefer straightforward, readable test doubles over over-engineered mocks
+
+### Still forbidden:
+- Hitting real external systems in unit tests (real `xcodebuild`, `xcrun`, AXe, filesystem writes/reads outside test harness)
+- Bypassing dependency injection for external effects
 
 ### OUR CORE PRINCIPLE
 
-**Simple Rule**: No mocking other than `createMockExecutor()` and `createMockFileSystemExecutor()` (and their noop variants).
+**Simple Rule**: Use dependency-injection mock executors for external boundaries; use Vitest mocking only for internal behavior.
 
 **Why This Rule Exists**:
-1. **Consistency**: All tests use the same mocking utilities, making them predictable and maintainable
-2. **Reliability**: Our utilities are thoroughly tested and handle edge cases properly
-3. **Architectural Enforcement**: Prevents bypassing our dependency injection patterns
-4. **Simplicity**: One clear rule instead of complex guidelines about what mocking is acceptable
+1. **Reliability**: External side effects stay deterministic and hermetic
+2. **Clarity**: Internal collaboration assertions remain concise and readable
+3. **Architectural Enforcement**: External boundaries are explicit in tool logic signatures
+4. **Maintainability**: Tests fail for behavior regressions, not incidental environment differences
 
 ### Integration Testing with Dependency Injection
 
-XcodeBuildMCP follows a **pure dependency injection** testing philosophy that eliminates vitest mocking:
+XcodeBuildMCP follows a dependency-injection testing philosophy for external boundaries:
 
 - ✅ **Test plugin interfaces** (public API contracts)
 - ✅ **Test integration flows** (plugin → utilities → external tools)
-- ✅ **Use dependency injection** with createMockExecutor()
-- ❌ **Never mock vitest functions** (vi.mock, vi.fn, etc.)
+- ✅ **Use dependency injection** with createMockExecutor()/createMockFileSystemExecutor() for external dependencies
+- ✅ **Use Vitest mocking when needed** for internal modules and collaborators
 
 ### Benefits
 
@@ -76,7 +63,7 @@ XcodeBuildMCP follows a **pure dependency injection** testing philosophy that el
 
 ### Automated Violation Checking
 
-To enforce the no-mocking policy, the project includes a script that automatically checks for banned testing patterns.
+To enforce external-boundary testing policy, the project includes a script that checks for architectural test-pattern violations.
 
 ```bash
 # Run the script to check for violations
@@ -91,7 +78,7 @@ This script is part of the standard development workflow and should be run befor
 - Manual mock executors: `const mockExecutor = async (...) => { ... }`
 - Manual filesystem mocks: `const mockFsDeps = { readFile: async () => ... }`
 - Manual server mocks: `const mockServer = { ... }`
-- Vitest mocking patterns: `vi.mock()`, `vi.fn()`, etc.
+- External side-effect patterns that bypass injected executors/filesystem dependencies
 
 #### ❌ FALSE POSITIVES (should NOT be flagged):
 - Test data tracking: `commandCalls.push({ ... })` - This is just collecting test data, not mocking behavior
@@ -118,7 +105,7 @@ Test → Plugin Handler → utilities → [DEPENDENCY INJECTION] createMockExecu
 ### What Gets Mocked
 - Command execution via `createMockExecutor()`
 - File system operations via `createMockFileSystemExecutor()`
-- Nothing else - all vitest mocking is banned
+- Internal modules can use Vitest mocks where appropriate
 
 ## Dependency Injection Strategy
 
@@ -359,8 +346,8 @@ describe('simulator-project re-exports', () => {
 import { vi, describe, it, expect, beforeEach } from 'vitest';
 import { z } from 'zod';
 
-// CRITICAL: NO VITEST MOCKING ALLOWED
-// Import ONLY what you need - no mock setup
+// Use dependency-injection mocks for external boundaries.
+// Vitest mocks are acceptable for internal collaborators when needed.
 
 import tool from '../tool_name.ts';
 import { createMockExecutor } from '../../utils/command.js';
@@ -1266,8 +1253,8 @@ npm run test:coverage -- src/plugins/simulator-workspace/
 ### Validation Scripts
 
 ```bash
-# Check for vitest mocking violations
-node scripts/check-code-patterns.js --pattern=vitest
+# Check for architectural pattern violations
+node scripts/check-code-patterns.js
 
 # Check dependency injection compliance
 node scripts/audit-dependency-container.js
@@ -1278,12 +1265,12 @@ node scripts/audit-dependency-container.js
 ## Best Practices Summary
 
 1. **Dependency injection**: Always use createMockExecutor() and createMockFileSystemExecutor()
-2. **No vitest mocking**: All vi.mock, vi.fn, etc. patterns are banned
+2. **External boundaries via DI**: mock command execution/filesystem with injected executors
 3. **Three dimensions**: Test input validation, command execution, and output processing
 4. **Literal expectations**: Use exact strings in assertions to catch regressions
 5. **Performance**: Ensure fast execution through proper mocking
 6. **Coverage**: Aim for 95%+ with focus on error paths
 7. **Consistency**: Follow standard patterns across all plugin tests
 8. **Test safety**: Default executors prevent accidental real system calls
 
-This testing strategy ensures robust, maintainable tests that provide confidence in plugin functionality while remaining resilient to implementation changes and completely eliminating vitest mocking dependencies.
+This testing strategy ensures robust, maintainable tests that provide confidence in plugin functionality while remaining resilient to implementation changes and keeping external boundaries deterministic.

scripts/check-code-patterns.js

@@ -11,11 +11,10 @@
  *   node scripts/check-code-patterns.js --help
  *
  * ARCHITECTURAL RULES ENFORCED:
- * 1. NO vitest mocking patterns (vi.mock, vi.fn, .mockResolvedValue, etc.)
+ * 1. External boundaries in tests should use dependency-injection utilities
  * 2. NO execSync usage in production code (use CommandExecutor instead)
- * 3. ONLY dependency injection with createMockExecutor() and createMockFileSystemExecutor()
- * 4. NO handler signature violations (handlers must have exact MCP SDK signatures)
- * 5. NO handler testing violations (test logic functions, not handlers directly)
+ * 3. NO handler signature violations (handlers must have exact MCP SDK signatures)
+ * 4. NO handler testing violations (test logic functions, not handlers directly)
  *
  * For comprehensive code quality documentation, see docs/dev/CODE_QUALITY.md
  *
@@ -49,7 +48,7 @@ OPTIONS:
   --help, -h        Show this help message
 
 PATTERN TYPES:
-  vitest           Check only vitest mocking violations (vi.mock, vi.fn, etc.)
+  vitest           Check only custom vitest policy violations (currently none)
   execsync         Check only execSync usage in production code
   handler          Check only handler signature violations
   handler-testing  Check only handler testing violations (testing handlers instead of logic functions)
@@ -77,28 +76,9 @@ const EXECSYNC_PATTERNS = [
   /^import\s+{[^}]*(?:exec|spawn|execSync)[^}]*}\s+from\s+['"](?:node:)?child_process['"]/m, // Named imports of functions
 ];
 
-// CRITICAL: ALL VITEST MOCKING PATTERNS ARE COMPLETELY FORBIDDEN
-// ONLY dependency injection with approved mock utilities is allowed
-const VITEST_GENERIC_PATTERNS = [
-  /vi\.mock\s*\(/, // vi.mock() - BANNED
-  /vi\.fn\s*\(/, // vi.fn() - BANNED
-  /vi\.mocked\s*\(/, // vi.mocked() - BANNED
-  /vi\.spyOn\s*\(/, // vi.spyOn() - BANNED
-  /vi\.clearAllMocks\s*\(/, // vi.clearAllMocks() - BANNED
-  /\.mockResolvedValue/, // .mockResolvedValue - BANNED
-  /\.mockRejectedValue/, // .mockRejectedValue - BANNED
-  /\.mockReturnValue/, // .mockReturnValue - BANNED
-  /\.mockImplementation/, // .mockImplementation - BANNED
-  /\.mockClear/, // .mockClear - BANNED
-  /\.mockReset/, // .mockReset - BANNED
-  /\.mockRestore/, // .mockRestore - BANNED
-  /\.toHaveBeenCalled/, // .toHaveBeenCalled - BANNED
-  /\.toHaveBeenCalledWith/, // .toHaveBeenCalledWith - BANNED
-  /MockedFunction/, // MockedFunction type - BANNED
-  /as MockedFunction/, // Type casting to MockedFunction - BANNED
-  /\bexecSync\b/, // execSync usage - BANNED (use executeCommand instead)
-  /\bexecSyncFn\b/, // execSyncFn usage - BANNED (use executeCommand instead)
-];
+// Vitest mocking is allowed for internal collaborators.
+// Keep this list empty unless a specific project policy requires certain vitest patterns to be blocked.
+const VITEST_GENERIC_PATTERNS = [];
 
 // APPROVED mock utilities - ONLY these are allowed
 const APPROVED_MOCK_PATTERNS = [
@@ -110,14 +90,8 @@ const APPROVED_MOCK_PATTERNS = [
   /\bcreateMockEnvironmentDetector\b/,
 ];
 
-// REFINED PATTERNS - Only flag ACTUAL vitest violations, not approved dependency injection patterns
-// Manual executors and mock objects are APPROVED when used for dependency injection
-const UNAPPROVED_MOCK_PATTERNS = [
-  // ONLY ACTUAL VITEST PATTERNS (vi.* usage) - Everything else is approved
-  /\bmock[A-Z][a-zA-Z0-9]*\s*=\s*vi\./, // mockSomething = vi.fn() - vitest assignments only
-
-  // No other patterns - manual executors and mock objects are approved for dependency injection
-];
+// Custom vitest restrictions can be added here if needed.
+const UNAPPROVED_MOCK_PATTERNS = [];
 
 // Function to check if a line contains unapproved mock patterns
 function hasUnapprovedMockPattern(line) {
@@ -615,8 +589,8 @@ function main() {
   console.log('🔍 XcodeBuildMCP Code Pattern Violations Checker\n');
   console.log(`🎯 Checking pattern type: ${patternFilter.toUpperCase()}\n`);
   console.log('CODE GUIDELINES ENFORCED:');
-  console.log('✅ ONLY ALLOWED: createMockExecutor() and createMockFileSystemExecutor()');
-  console.log('❌ BANNED: vitest mocking patterns (vi.mock, vi.fn, .mockResolvedValue, etc.)');
+  console.log('✅ External boundaries in tests should use createMockExecutor()/createMockFileSystemExecutor()');
+  console.log('✅ Vitest mocking is allowed for internal collaborators');
   console.log('❌ BANNED: execSync usage in production code (use CommandExecutor instead)');
   console.log('ℹ️  TypeScript patterns: Handled by ESLint with proper test exceptions');
   console.log(
@@ -898,12 +872,11 @@ function main() {
   if (needsConversion.length > 0) {
     console.log(`🚨 CRITICAL ACTION REQUIRED (TEST FILES):`);
     console.log(`=======================================`);
-    console.log(`1. IMMEDIATELY remove ALL vitest mocking from ${needsConversion.length} files`);
-    console.log(`2. BANNED: vi.mock(), vi.fn(), .mockResolvedValue(), .toHaveBeenCalled(), etc.`);
+    console.log(`1. Fix architectural violations in ${needsConversion.length} files`);
     console.log(
-      `3. BANNED: Testing handlers directly (.handler()) - test logic functions with dependency injection`,
+      `2. BANNED: Testing handlers directly (.handler()) - test logic functions with dependency injection`,
     );
-    console.log(`4. ONLY ALLOWED: createMockExecutor() and createMockFileSystemExecutor()`);
+    console.log(`3. Use injected executors/filesystem mocks for external side effects`);
     console.log(`4. Update plugin implementations to accept executor?: CommandExecutor parameter`);
     console.log(`5. Run this script again after each fix to track progress`);
     console.log('');
@@ -974,7 +947,7 @@ function main() {
   if (!hasViolations && mixed.length === 0) {
     console.log(`🎉 ALL FILES COMPLY WITH PROJECT STANDARDS!`);
     console.log(`==========================================`);
-    console.log(`✅ All files use ONLY createMockExecutor() and createMockFileSystemExecutor()`);
+    console.log(`✅ External boundary tests use injected executors/filesystem dependencies`);
     console.log(`✅ All files follow TypeScript best practices (no unsafe casts)`);
     console.log(`✅ All handler signatures comply with MCP SDK requirements`);
     console.log(`✅ All utilities properly use CommandExecutor dependency injection`);