adapter: Prototype native-applescript transport + Apple Mail adapter

[mickdarling]

Summary

Build a working prototype of the native-applescript transport and Apple Mail adapter to validate the spec design before finalizing normative text. Ship code first, spec second.

Context

The spec issues (#227–#231) define the design space but several decisions (transport vs protocol split, maps_to syntax, JXA vs AppleScript for serialization) need empirical validation. This issue tracks the prototype implementation that informs those decisions.

Prototype Scope

Phase 1: Minimal Transport

• Implement native-applescript transport plugin in TypeScript
• Execute AppleScript via child_process.execFile('osascript', ...)
• Parameterized template system (no raw string interpolation)
• JSON output via JXA wrapper or AppleScript-to-JSON handler
• Error capture and mapping

Phase 2: Apple Mail Operations

• Implement core READ operations against Apple Mail
• Validate the maps_to syntax works for real AppleScript patterns
• Test with multiple accounts, large mailboxes, various message types
• Measure performance (latency per operation, batch feasibility)

Phase 3: Pipeline Integration

• Hand-author a discovery bundle from Mail.sdef
• Feed through existing schema builder
• Feed through existing generator
• Validate the generated adapter works end-to-end

Phase 4: Interrogator Extension

• Parse Mail.sdef XML
• Produce discovery bundle automatically
• Compare auto-generated bundle against hand-authored one
• Identify gaps in CRUDE classification heuristics

Prototype Location

• @mcpaql/tools — interrogator extension (new --transport native-applescript mode)
• @mcpaql/adapter-generator — may need minor changes for non-HTTP maps_to
• New adapter package in examples/ repo or as standalone

Key Questions to Answer

1. Is JXA (osascript -l JavaScript) reliable enough for all Mail operations, or do some require native AppleScript?
2. What is the latency profile? Can we batch multiple property reads into a single osascript call?
3. Does the existing maps_to → request builder pipeline in the generator need structural changes, or just a new code path?
4. How well do .sdef files map to CRUDE classification? What percentage needs manual override?
5. Are there AppleScript patterns that don't fit the parameterized template model?

Acceptance Criteria

• Working transport that executes parameterized AppleScript
• At least 5 Apple Mail READ operations working end-to-end
• Performance benchmarks documented
• Design decision recommendations for spec: Define native-applescript transport plugin specification #227 (transport vs protocol split, maps_to syntax)
• Findings documented for spec refinement

Dependencies

• Informed by spec: Define native-applescript transport plugin specification #227, spec: Define scripting dictionary interrogation mode for native-applescript #228, spec: Define AppleScript parameter sanitization and injection prevention #229, spec: Define AppleScript type serialization contract (AppleScript types ↔ JSON) #230
• Results feed back into those spec issues