refactor(12/12): add snapshot test fixtures and benchmarks (#330)

This is **PR 12 of 12**, the final PR in the stacked series that decouples the rendering pipeline from MCP transport. Depends on PR 11.

Adds the snapshot test suite and performance benchmarks that validate the entire rendering pipeline end-to-end. These are large in line count but are almost entirely test fixtures (expected output files) and benchmark scripts.

The snapshot test infrastructure captures the rendered output of tool invocations and compares against expected fixtures. This provides regression protection for the rendering pipeline -- any change to event formatting, diagnostic grouping, or output ordering will be caught by a fixture mismatch.

**Test harness** (`src/snapshot-tests/`):
- `harness.ts`: Core test runner that invokes tools with mock executors and captures rendered output
- `fixture-io.ts`: Reads/writes fixture files, handles normalization (timestamps, paths, UUIDs)
- `flowdeck-fixture-io.ts`: Flowdeck-specific fixture handling
- `normalize.ts`: Output normalization for stable comparisons across environments
- `resource-harness.ts`: Resource-specific snapshot testing

**Fixtures**: Expected output files for each tool covering success, error, and edge case scenarios. These serve as living documentation of what each tool's output looks like.

Performance benchmarks for the rendering pipeline and xcodebuild parsing:
- Parser throughput: lines/second for xcodebuild output parsing
- Render session performance: events/second for text and JSON strategies
- End-to-end tool invocation timing

These benchmarks establish baselines and can be run in CI to catch performance regressions.

This PR is large by line count but low in conceptual complexity. The fixture files are auto-generated expected outputs. The benchmark scripts are straightforward timing loops. The meaningful code is the ~500 lines of test harness infrastructure.

- PR 1-11/12: All code and configuration changes
- **PR 12/12** (this PR): Snapshot tests and benchmarks

- [ ] `npx vitest run` passes -- snapshot tests match expected fixtures
- [ ] `npx vitest run --config vitest.snapshot.config.ts` runs snapshot suite specifically
- [ ] Benchmarks execute without errors (performance numbers are informational)

Author: cameroncooke

docs/dev/ARCHITECTURE.md

@@ -201,11 +201,12 @@ Each tool is implemented in TypeScript and follows a standardized pattern that s
 
 ```typescript
 import { z } from 'zod';
-import { createTypedTool } from '../../../utils/typed-tool-factory.js';
+import { createTypedTool, getHandlerContext } from '../../../utils/typed-tool-factory.js';
 import type { CommandExecutor } from '../../../utils/execution/index.js';
 import { getDefaultCommandExecutor } from '../../../utils/execution/index.js';
 import { log } from '../../../utils/logging/index.js';
-import { createTextResponse, createErrorResponse } from '../../../utils/responses/index.js';
+import { withErrorHandling } from '../../../utils/tool-error-handling.js';
+import { header, statusLine } from '../../../utils/tool-event-builders.js';
 
 // 1. Define the Zod schema for parameters
 const someToolSchema = z.object({
@@ -216,41 +217,46 @@ const someToolSchema = z.object({
 // 2. Infer the parameter type from the schema
 type SomeToolParams = z.infer<typeof someToolSchema>;
 
-// 3. Implement the core logic in a separate, testable function
-// This function receives strongly-typed parameters and an injected executor.
+// 3. Implement the core logic as an event-emitting function.
+// Handlers emit structured events via ctx.emit() instead of returning ToolResponse.
 export async function someToolLogic(
   params: SomeToolParams,
   executor: CommandExecutor,
-): Promise<ToolResponse> {
-  log('info', `Executing some_tool with param: ${params.requiredParam}`);
-
-  try {
-    const result = await executor(['some', 'command'], 'Some Tool Operation');
-
-    if (!result.success) {
-      return createErrorResponse('Operation failed', result.error);
-    }
-
-    return createTextResponse(`✅ Success: ${result.output}`);
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    return createErrorResponse('Tool execution failed', errorMessage);
-  }
+): Promise<void> {
+  const headerEvent = header('Some Tool', [
+    { label: 'Param', value: params.requiredParam },
+  ]);
+  const ctx = getHandlerContext();
+
+  return withErrorHandling(
+    ctx,
+    async () => {
+      const result = await executor(['some', 'command'], 'Some Tool Operation');
+
+      if (!result.success) {
+        ctx.emit(headerEvent);
+        ctx.emit(statusLine('error', `Operation failed: ${result.error}`));
+        return;
+      }
+
+      ctx.emit(headerEvent);
+      ctx.emit(statusLine('success', `Success: ${result.output}`));
+    },
+    {
+      header: headerEvent,
+      errorMessage: ({ message }) => `Tool execution failed: ${message}`,
+    },
+  );
 }
 
-// 4. Export the tool definition for auto-discovery
-export default {
-  name: 'some_tool',
-  description: 'Tool description for AI agents. Example: some_tool({ requiredParam: "value" })',
-  schema: someToolSchema.shape, // Expose shape for MCP SDK
-
-  // 5. Create the handler using the type-safe factory
-  handler: createTypedTool(
-    someToolSchema,
-    someToolLogic,
-    getDefaultCommandExecutor,
-  ),
-};
+// 4. Export schema shape and handler for manifest-driven auto-discovery
+export const schema = someToolSchema.shape;
+
+export const handler = createTypedTool(
+  someToolSchema,
+  someToolLogic,
+  getDefaultCommandExecutor,
+);
 ```
 
 This pattern ensures that:

src/mcp/tools/debugging/__tests__/debugging-tools.test.ts

@@ -47,7 +47,6 @@ import {
 } from '../debug_variables.ts';
 import { allText, runLogic } from '../../../../test-utils/test-helpers.ts';
 
-
 function createMockBackend(overrides: Partial<DebuggerBackend> = {}): DebuggerBackend {
   return {
     kind: 'dap',

src/mcp/tools/device/__tests__/get_device_app_path.test.ts

@@ -9,7 +9,6 @@ import { schema, handler, get_device_app_pathLogic } from '../get_device_app_pat
 import { sessionStore } from '../../../../utils/session-store.ts';
 import { runLogic } from '../../../../test-utils/test-helpers.ts';
 
-
 describe('get_device_app_path plugin', () => {
   beforeEach(() => {
     sessionStore.clear();

src/mcp/tools/device/__tests__/install_app_device.test.ts

@@ -5,7 +5,6 @@ import { schema, handler, install_app_deviceLogic } from '../install_app_device.
 import { sessionStore } from '../../../../utils/session-store.ts';
 import { allText, runLogic } from '../../../../test-utils/test-helpers.ts';
 
-
 describe('install_app_device plugin', () => {
   beforeEach(() => {
     sessionStore.clear();

src/mcp/tools/device/__tests__/launch_app_device.test.ts

@@ -8,7 +8,6 @@ import { schema, handler, launch_app_deviceLogic } from '../launch_app_device.ts
 import { sessionStore } from '../../../../utils/session-store.ts';
 import { allText, runLogic } from '../../../../test-utils/test-helpers.ts';
 
-
 describe('launch_app_device plugin (device-shared)', () => {
   beforeEach(() => {
     sessionStore.clear();

src/mcp/tools/device/__tests__/list_devices.test.ts

@@ -216,7 +216,10 @@ describe('list_devices plugin (device-shared)', () => {
       const text = allText(result);
       expect(text).toContain('Test iPhone');
       expect(text).toContain('test-device-123');
-      expect(result.nextStepParams).toBeUndefined();
+      expect(result.nextStepParams).toEqual({
+        build_device: { scheme: 'YOUR_SCHEME', deviceId: 'UUID_FROM_ABOVE' },
+        install_app_device: { deviceId: 'UUID_FROM_ABOVE', appPath: 'PATH_TO_APP' },
+      });
     });
 
     it('should return successful xctrace fallback response', async () => {

src/mcp/tools/device/__tests__/stop_app_device.test.ts

@@ -5,7 +5,6 @@ import { schema, handler, stop_app_deviceLogic } from '../stop_app_device.ts';
 import { sessionStore } from '../../../../utils/session-store.ts';
 import { allText, runLogic } from '../../../../test-utils/test-helpers.ts';
 
-
 describe('stop_app_device plugin', () => {
   beforeEach(() => {
     sessionStore.clear();