OpenPets Dev 6ab3bb64d8 feat(rebrand): rename OpenPets to FamiliarOS and pets to familiars

- Rename all user-facing and technical identifiers from OpenPets/Pet to FamiliarOS/Familiar.
- Rename packages from @open-pets/* to @familiaros/*; rename install-pet/pet-format packages.
- Rename plugin IDs and directories from openpets.* to familiaros.*.
- Rename IPC namespace from openpets:* to familiaros:* and state filenames from openpets-* to familiaros-* with legacy migration.
- Rename source files (pet-window, built-in-pet, default-pet-controller, etc.) to familiar equivalents.
- Update locales (en, es-419, ja, ko, pt-BR, zh-Hans, zh-Hant) and tray/pet context menu strings.
- Add Familiar naming feature: preference, settings input, tray menu display.
- Update assets and packaging config; all desktop tests pass.

2026-06-17 01:42:08 +00:00

3.3 KiB

Raw Blame History

packages/client/

Core IPC client library for FamiliarOS desktop app communication.

Responsibility

Provides the foundational client library for all FamiliarOS integrations. Handles discovery file reading, TCP socket connections (including WSL cross-platform), request/response protocol, and high-level familiar 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 FamiliarOSClientError 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: createFamiliarOSClient(options) returns FamiliarOSClient interface
Methods: hello(), status(), listPets(), installPet(), acquireLease(), heartbeatLease(), releaseLease(), react(), say()
Lease-aware operations for multi-familiar 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):

@familiaros/cli - CLI commands
@familiaros/mcp - MCP tool implementations
@familiaros/claude - Hook execution
@familiaros/opencode - Plugin runtime
@familiaros/install-familiar - Direct installation fallback

Desktop App: Communicates with FamiliarOS desktop app via:

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

Exports:

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

Contracts:

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

3.3 KiB Raw Blame History