openpetswithchatandmcp/packages/client/codemap.md

packages/client/

Core IPC client library for OpenPets desktop app communication.

Responsibility

Provides the foundational client library for all OpenPets integrations. Handles discovery file reading, TCP socket connections (including WSL cross-platform), request/response protocol, and high-level pet operations (status, list, install, lease, react, say).

Design/Patterns

Protocol Layer (protocol.ts):

• Defines IPC protocol version (v1), message limits (16KB), timeouts (2s connect, 3s response)
• Request/response types with discriminated union (ok: true/false)
• Reaction validation against allowed enum values
• Custom OpenPetsClientError with error codes

Discovery Layer (discovery.ts):

• Cross-platform discovery file path resolution (macOS, Windows, Linux/XDG)
• File validation (size, permissions, symlink checks)
• Endpoint validation: Unix sockets, Windows named pipes, TCP (IPv4)
• TCP/WSL cross-platform support: Windows desktop → WSL client via private IPs
• Security: XDG_RUNTIME_DIR permission checks (0o700, ownership)

TCP Endpoint Security:

• IPv4 only (no hostnames)
• Private/local addresses only:
  • Loopback: 127.0.0.0/8
  • Private: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  • Link-local: 169.254.0.0/16
• Rejects 0.0.0.0, public IPs, hostnames
• Enables WSL clients to connect to Windows desktop app

Client Layer (index.ts):

• Factory pattern: createOpenPetsClient(options) returns OpenPetsClient interface
• Methods: hello(), status(), listPets(), installPet(), acquireLease(), heartbeatLease(), releaseLease(), react(), say()
• Lease-aware operations for multi-pet targeting
• Result parsers with validation

Socket Management:

• Node.js net.createConnection() for TCP/Unix sockets/Windows named pipes
• Dual timeout handling (connect + response)
• Line-delimited JSON protocol (\n separator)
• Buffer size enforcement (16KB max)

Flow

Client Method Call
    ↓
readDiscoveryFile() → Parse ipc.json (token, endpoint)
    ↓
sendRequest() → Build request (id, version, token, method, params)
    ↓
net.createConnection(endpoint) → Write JSON + newline
    ↓
Wait for response (buffer until newline)
    ↓
parseIpcResponse() → Validate shape, return result or throw

TCP/WSL Cross-Platform Flow:

WSL Client → readDiscoveryFile()
    ↓
Endpoint: tcp://192.168.x.x:port (Windows host IP)
    ↓
validateDiscovery() → allowsCrossPlatformDiscovery()
    ↓
net.createConnection({ host, port }) → Windows desktop app

Integration Points

Consumers (all depend on this package):

• @open-pets/cli - CLI commands
• @open-pets/mcp - MCP tool implementations
• @open-pets/claude - Hook execution
• @open-pets/opencode - Plugin runtime
• @open-pets/install-pet - Direct installation fallback

Desktop App: Communicates with OpenPets desktop app via:

• Unix domain socket (macOS/Linux)
• Windows named pipe (Windows)
• TCP socket (WSL cross-platform)

Exports:

• createOpenPetsClient() - Main factory
• sendRequest() - Low-level request function
• readDiscoveryFile(), getDiscoveryFilePath() - Discovery utilities
• parseIpcEndpoint(), validateEndpoint() - Endpoint handling
• OpenPetsClientError, error codes, types

Contracts:

• contracts/client-protocol.contract.ts - Runtime protocol validation tests