Add simulator video recording tool (record_sim) + AXe v1.1.0

[cameroncooke]

Summary

Adds an iOS simulator video recording tool and updates the bundled AXe to v1.1.0 (which includes the new video recording feature).

What’s Included

• Tool: record_sim (simulator group)
  • Params: simulatorUuid (required), start | stop (mutually exclusive), fps (default 30), outputFile (required on stop)
  • UX: If start=true and outputFile is provided, it is ignored with a subtle note; the response shows a “how to stop” hint
• Util: Video capture session manager
  • Tracks one active session per simulator UDID
  • Starts AXe record-video as a long‑running process, aggregates stdout/stderr, and stops via SIGINT
  • Parses the finalized MP4 path from AXe output and moves/renames it on stop
• AXe helpers
  • isAxeAtLeastVersion with robust semver extraction (prefers AXe vX.Y.Z, falls back to highest semver token)
  • DI‑friendly signature for testing; unit tests added
• Bundling
  • scripts/bundle-axe.sh updated to fetch AXe v1.1.0
• Documentation
  • README updated (Video Capture + bundling note)
  • docs/TOOLS.md regenerated (now lists record_sim under the simulator workflow)

Validation

• Formatting, lint, typecheck: pass
• Build: pass
• Tests: pass (84 files; >1,100 tests, a few skipped)

Usage (Reloaderoo)

Start:

npx reloaderoo inspect call-tool record_sim \
  --params '{"simulatorUuid":"<SIM_UDID>","start":true,"fps":30}' \
  -- node build/index.js

Stop and save:

npx reloaderoo inspect call-tool record_sim \
  --params '{"simulatorUuid":"<SIM_UDID>","stop":true,"outputFile":"./recordings/sim-recording.mp4"}' \
  -- node build/index.js

Prereq for real recordings (unit tests don’t require this):

npm run bundle:axe && npm run build

Follow‑ups (Optional)

• Add a list_active_recordings tool to enumerate in‑flight sessions (UDID, sessionId, startedAt).

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/record-sim-video-capture-axe-1.1.0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude finished @cameroncooke's task —— View job

---

Code Review Complete ✅

I've conducted a comprehensive review of PR #112 that adds the record_sim video recording tool and AXe v1.1.0 support. Here's my detailed feedback:

Review Tasks

• Analyze core record_sim tool implementation
• Review video capture session manager utility
• Examine AXe helper improvements and version checking
• Assess test coverage and quality
• Check adherence to project patterns and conventions
• Provide comprehensive feedback on code quality and potential issues

---

Overall Assessment: High Quality Implementation 🌟

This PR demonstrates excellent engineering practices with comprehensive dependency injection, robust error handling, and thorough test coverage. The implementation follows XcodeBuildMCP patterns consistently.

Code Quality & Best Practices ✅

Excellent Patterns

• Dependency Injection: Perfect implementation in record_sim_videoLogic() with injected executors, AXe helpers, video capture utilities, and file system operations
• Type Safety: Strong Zod schema validation with mutually exclusive constraints and custom refinements
• Separation of Concerns: Clean separation between tool handler and testable logic function
• Error Handling: Comprehensive error handling with graceful degradation and meaningful error messages

Architecture Compliance

• Follows XcodeBuildMCP's focused facades pattern (src/utils/video-capture/index.ts)
• Uses createTypedTool factory for type-safe tool creation
• Consistent response formatting with utility functions
• Proper use of TypeScript file extensions (.ts) for relative imports

Security Considerations ✅

Secure Practices

• Input Validation: UUID validation prevents injection attacks
• File Path Handling: Uses dirname() with recursive directory creation for safe output file handling
• Process Management: Proper signal handling (SIGINT/SIGTERM) prevents orphaned processes
• Resource Cleanup: Graceful cleanup of temp files and processes on failure

Potential Considerations

• File path validation could be enhanced to prevent directory traversal (though current UUID + path handling provides good protection)
• Consider adding file size limits for output videos to prevent disk exhaustion

Performance Considerations ✅

Efficient Design

• Session Management: Per-UUID session tracking prevents conflicts
• Process Reuse: Long-running AXe processes for recording (start once, stop later)
• Buffer Management: Efficient stdout/stderr aggregation for path parsing
• Resource Cleanup: Proper process termination and file cleanup

Potential Optimizations

• Consider adding maximum recording duration limits
• Buffer size could be bounded to prevent memory issues on very long recordings

Test Coverage Assessment: Excellent ✅

Comprehensive Coverage

• Three-Dimensional Testing: Input validation, command generation, and output processing all covered
• Edge Cases: Mutually exclusive parameters, missing output files, version gates, and error conditions
• Dependency Injection: All external dependencies properly mocked using project patterns
• End-to-End Scenarios: Complete start/stop workflows with file renaming tested

Test Quality Highlights

• Uses createMockExecutor() and createMockFileSystemExecutor() following project standards
• No Vitest Mocking: Correctly avoids banned vi.mock() patterns
• Clear test organization with descriptive test names
• Proper assertions on both success and error paths

Implementation Details Review

record_sim.ts - Excellent Implementation

// Strong parameter validation with mutually exclusive constraints
.refine((v) => (v.stop ? typeof v.outputFile === 'string' && v.outputFile.length > 0 : true), {
  message: 'outputFile is required when stop=true',
  path: ['outputFile'],
})

video_capture.ts - Robust Session Management

• Global session map with proper UUID-based isolation
• Signal handler registration for cleanup on process termination
• Intelligent stdout parsing with regex for MP4 path extraction
• Process lifecycle management with graceful SIGINT handling

axe-helpers.ts - Smart Version Detection

// Excellent semver parsing with fallback strategies
const preferred = output.match(/\bAXe(?:\s+version)?\s+v?(\d+\.\d+\.\d+)\b/i);
// Falls back to highest version if preferred pattern not found

Minor Suggestions for Enhancement

Documentation

1. Consider adding JSDoc comments for the main record_sim_videoLogic function parameters
2. The regex pattern in parseLastAbsoluteMp4Path could benefit from an inline comment explaining the pattern

Error Messages

• Error messages are clear and actionable throughout
• Good use of structured responses with multiple content blocks

Future Enhancements (Optional)

• Consider adding a list_active_recordings tool as mentioned in the PR description
• Maximum recording duration parameter could be useful
• Progress indicators for long recordings

Security & Performance: No Critical Issues ✅

The implementation demonstrates strong security practices with proper input validation, secure file handling, and resource management. Performance is well-considered with efficient session management and cleanup.

Conclusion

This is an exemplary implementation that demonstrates advanced software engineering practices. The code is production-ready with excellent test coverage, robust error handling, and clean architecture. The dependency injection pattern makes the code highly testable and maintainable.

Recommendation: Approve ✅

---

| Branch: feat/record-sim-video-capture-axe-1.1.0

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cameroncooke/XcodeBuildMCP/xcodebuildmcp@112

commit: f27c542