6ab3bb64d8
- 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.
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# packages/
|
|
|
|
Monorepo workspace containing all FamiliarOS npm packages. Each package is independently publishable with its own versioning.
|
|
|
|
## Responsibility
|
|
|
|
Provides modular, reusable components for the FamiliarOS ecosystem:
|
|
- **familiar-format**: Package marker interface for type identification
|
|
- **agent-events**: Speech pools and validation for agent feedback messages
|
|
- **client**: Core IPC client for communicating with FamiliarOS desktop app
|
|
- **cli**: Main CLI tool for configuring agents and managing familiars
|
|
- **mcp**: MCP server implementation for agent integration
|
|
- **opencode**: OpenCode editor integration (plugin, config management)
|
|
- **claude**: Claude Code integration (hooks, MCP config)
|
|
- **cursor**: Cursor editor integration (MCP config, project rules)
|
|
- **pi**: Pi coding-agent extension integration (event hooks, slash commands)
|
|
- **install-familiar**: Standalone familiar installer from gallery catalog
|
|
|
|
## Design/Patterns
|
|
|
|
**Workspace Pattern**: Uses pnpm workspaces with `workspace:*` dependencies for internal linking.
|
|
|
|
**Package Structure**: Each package follows consistent structure:
|
|
- `src/` - TypeScript source
|
|
- `dist/` - Compiled output (not committed)
|
|
- `package.json` - Standard npm metadata with exports map
|
|
- `contracts/` - Runtime contract validation tests (client package)
|
|
- Contract check files (`check-*.ts`) for runtime validation (other packages)
|
|
|
|
**ESM-First**: All packages are ESM (`"type": "module"`) with dual exports for types.
|
|
|
|
**Versioning**: Independent versioning per package (currently 2.1.x for active integrations).
|
|
|
|
## Flow
|
|
|
|
```
|
|
CLI Entry (packages/cli/src/index.ts)
|
|
├── Configures Claude → @familiaros/claude
|
|
├── Configures OpenCode → @familiaros/opencode
|
|
├── Configures Cursor → @familiaros/cursor
|
|
├── Spawns MCP server → @familiaros/mcp
|
|
└── Uses IPC client → @familiaros/client
|
|
|
|
MCP Server (packages/mcp/src/index.ts)
|
|
├── Registers tools (status, react, say)
|
|
└── Communicates via @familiaros/client
|
|
|
|
OpenCode Plugin (packages/opencode/src/plugin.ts)
|
|
└── Hooks into editor events → @familiaros/client
|
|
|
|
Claude Hooks (packages/claude/src/hooks.ts)
|
|
└── Processes hook events → @familiaros/client
|
|
|
|
Cursor Setup (packages/cursor/src/cursor-project-setup.ts)
|
|
└── Writes MCP config + rules → @familiaros/client
|
|
|
|
Pi Extension (packages/pi/src/extension.ts)
|
|
└── Registers Pi extension hooks/commands → @familiaros/client
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
**Inter-Package Dependencies**:
|
|
- `cli` depends on: `client`, `claude`, `mcp`, `opencode`, `cursor`
|
|
- `mcp` depends on: `client`
|
|
- `claude` depends on: `client`, `agent-events`
|
|
- `opencode` depends on: `client`, `agent-events`
|
|
- `cursor` depends on: `client`
|
|
- `pi` depends on: `client`, `agent-events` and declares optional `@earendil-works/pi-coding-agent` peer support
|
|
- `install-familiar` depends on: `client`
|
|
|
|
**External Integrations**:
|
|
- `@modelcontextprotocol/sdk` - MCP protocol implementation
|
|
- `jsonc-parser` - JSON with comments parsing for OpenCode configs
|
|
- `yauzl` - ZIP extraction for familiar downloads
|
|
- `zod` - Schema validation in MCP tools
|
|
|
|
**Desktop App Communication**:
|
|
All packages ultimately communicate with the FamiliarOS desktop app via the IPC protocol defined in `client/src/protocol.ts`, supporting Unix sockets, Windows named pipes, and TCP (for WSL cross-platform).
|