Introduce MachineService abstraction layer for multi-backend support

[hessius]

Context

MeticAI currently has two deployment targets that speak to the machine via different paths:

1. Docker/Web — React app → MeticAI Python server → MQTT (meticulous-addon) → machine
2. iOS (future) — React app → machine's native HTTP REST + Socket.IO directly

To support both from the same codebase without a fork, a MachineService abstraction needs to sit between UI components and machine communication. This is a non-breaking, behaviour-identical refactor — it reorganises existing code behind a typed interface without changing any visible functionality.

Goal

Introduce a MachineService TypeScript interface with a MeticAIAdapter implementation that wraps the current stack. All machine commands and telemetry subscriptions route through this interface. Future adapters can be added without touching any component code.

Architecture

Components / Hooks
      ↓
useMachineService()   ← React context hook
      ↓
MachineService        ← TypeScript interface
      ↓
MeticAIAdapter        ← Wraps existing mqttCommands.ts + useWebSocket
      ↓
MeticAI Python server (unchanged)
      ↓
meticulous-addon / pyMeticulous (untouched)

Interface Design

// apps/web/src/services/machine/MachineService.ts

export interface MachineService {
  // Commands
  start(): Promise<CommandResult>
  stop(): Promise<CommandResult>
  abort(): Promise<CommandResult>
  continue(): Promise<CommandResult>
  tare(): Promise<CommandResult>
  preheat(): Promise<CommandResult>
  purge(): Promise<CommandResult>
  homePlunger(): Promise<CommandResult>
  loadProfile(name: string): Promise<CommandResult>
  setBrightness(value: number): Promise<CommandResult>
  enableSounds(enabled: boolean): Promise<CommandResult>

  // Telemetry
  subscribe(listener: (state: MachineState) => void): () => void

  // Profiles & history (async data)
  listProfiles(): Promise<Profile[]>
  getProfile(id: string): Promise<Profile>
  createProfile(profile: Profile): Promise<Profile>
  deleteProfile(id: string): Promise<void>
  getLastProfile(): Promise<Profile | null>

  // Shot history
  getHistory(): Promise<ShotSummary[]>
  getShot(id: string): Promise<Shot>
}

export type CommandResult = { success: boolean; message?: string }

Files to Create

File	Purpose
apps/web/src/services/machine/MachineService.ts	Interface + shared types
apps/web/src/services/machine/MeticAIAdapter.ts	Implementation wrapping current server API
apps/web/src/services/machine/MachineServiceContext.tsx	React context provider
apps/web/src/hooks/useMachineService.ts	Consumer hook

Files to Update

File	Change
apps/web/src/lib/mqttCommands.ts	Keep as-is; MeticAIAdapter delegates to it — no deletion
apps/web/src/hooks/useWebSocket.ts	Keep as-is; adapter wraps it for subscribe()
Components using mqttCommands directly	Import via useMachineService() instead
apps/web/src/App.tsx	Wrap with MachineServiceProvider

MeticAIAdapter Implementation Notes

The adapter is a thin delegation layer — it wraps what already exists:

• Commands → delegate to functions in mqttCommands.ts (unchanged)
• subscribe() → delegate to useWebSocket (unchanged)
• Profiles / history → delegate to existing API fetch calls in route-specific hooks

The adapter does not introduce any new network calls or behaviour.

What This Enables

Once in place, a future MachineDirectAdapter can be written against the Meticulous machine's native API (/api/v1/* + Socket.IO) and dropped in — zero component changes required. Adapter selection is handled at the provider level via build config or runtime environment detection.

Out of Scope

• MachineDirectAdapter implementation (separate issue)
• Any changes to the Python backend
• Any changes to meticulous-addon or pyMeticulous

Acceptance Criteria

• MachineService interface defined and exported
• MeticAIAdapter passes all existing functionality through correctly
• useMachineService() hook available and used by at least the primary machine-control components (LiveShotView, ControlCenter, PourOverView)
• All existing tests continue to pass
• No visible behaviour change for end users

[hessius]

Implementation Status: ✅ Complete

PR #262 fully implements this issue:

MachineService Layer:

• Created MachineService.ts interface defining all command, telemetry, and profile methods
• Created MeticAIAdapter.ts implementing the interface using existing APIs
• Created MachineServiceContext.tsx for React dependency injection
• Created useMachineService.ts hook with throw-if-missing guard

Migration:

• Wrapped App.tsx root with MachineServiceProvider
• Migrated all four primary consumers:
  • LiveShotView.tsx
  • ControlCenter.tsx
  • ControlCenterExpanded.tsx
  • PourOverView.tsx

Verification:

• All 277 frontend tests pass
• Zero behaviour change (pure refactor)
• TypeScript compiles clean

The abstraction is now ready for future test mocking and alternative implementations.

[hessius]

Research Update: MeticulousHome Repository Findings (Issue #283)

Key findings for the MachineService abstraction:

espresso-api Already Provides the Adapter Pattern

@meticulous-home/espresso-api (v0.10.11) is a production-grade TypeScript API client with 47+ methods and built-in Socket.IO. This can serve as the foundation for MachineDirectAdapter rather than building from scratch.

Two-Adapter Architecture Confirmed

MachineService interface
├── PythonProxyAdapter  → our FastAPI backend → pyMeticulous v0.3.1 (55 methods)
└── MachineDirectAdapter → @meticulous-home/espresso-api (47 methods)
                          + supplemental REST for abort/purge/home

API Surface Mapping

• pyMeticulous (Python, server-side): 55 methods, 10 action types including HOME/PURGE/ABORT
• espresso-api (TypeScript, client-side): 47 methods, 8 action types (missing HOME/PURGE/ABORT)
• Backend ground truth: 38+ endpoint groups, 12+ Socket.IO event types

Gap Handling

The TS API gaps (abort, purge, home, history export, bulk import) need either:

1. Direct REST calls as supplements in MachineDirectAdapter, or
2. PRs to the upstream meticulous-typescript-api repo

Full analysis: #283