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.
97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# packages/cli/
|
|
|
|
Main CLI tool for FamiliarOS agent configuration and familiar management.
|
|
|
|
## Responsibility
|
|
|
|
Primary user-facing CLI for the FamiliarOS ecosystem. Provides commands for: installing familiars from gallery, configuring projects for Claude/OpenCode/Cursor agents, running MCP server wrapper, executing Claude hooks, and direct familiar interaction (status, react, say).
|
|
|
|
## Design/Patterns
|
|
|
|
**Command Router**: `main()` dispatches to subcommands based on `process.argv[2]`:
|
|
- `install <familiar-id>` - Install familiar via running app
|
|
- `configure` - Interactive project setup for Claude, OpenCode, or Cursor
|
|
- `status` - Check FamiliarOS desktop app connectivity and print JSON status
|
|
- `familiars` - List installed familiars with flags (default, broken)
|
|
- `react <reaction>` - Send reaction to desktop app
|
|
- `say <message> [--reaction <reaction>]` - Display message on familiar
|
|
- `mcp` - Spawn MCP server (delegates to `@familiaros/mcp`)
|
|
- `hook` - Execute Claude hook from stdin
|
|
|
|
**Configuration Flow** (`configureProject`):
|
|
1. Resolve project directory (symlink/escape checks)
|
|
2. Route to agent-specific handler (claude/opencode/cursor)
|
|
3. For Claude: Assert availability, list familiars, build MCP config, write hooks
|
|
4. For OpenCode: Prepare and write OpenCode config via `@familiaros/opencode`
|
|
5. For Cursor: Configure MCP in `.cursor/mcp.json`, optional rules in `.cursor/rules/familiaros.mdc`
|
|
|
|
**Cursor Configuration**:
|
|
- `--with-rules` - Install MCP + project rules
|
|
- `--rules-only` - Install only `.cursor/rules/familiaros.mdc`
|
|
- `--remove-rules` - Remove managed rules file
|
|
- Status classification: `not_installed`, `installed`, `needs_update`, `conflict`, `error`
|
|
- Atomic writes with backup creation
|
|
|
|
**Safety Checks**:
|
|
- Project path validation (no symlinks, must be directory)
|
|
- `.claude`/`.cursor`/`.opencode` directory safety (no symlinks, path containment)
|
|
- Settings file atomic writes (temp + rename pattern)
|
|
- Shell argument quoting for command injection prevention
|
|
|
|
**Familiar Resolution** (`resolveConfiguredPet`):
|
|
- Validates explicit `--familiar` argument
|
|
- Otherwise: fetches installed familiars, interactive TTY prompt
|
|
- Validates selected familiar is not broken
|
|
|
|
## Flow
|
|
|
|
```
|
|
familiaros configure --agent claude --familiar <id> --cwd <dir>
|
|
↓
|
|
resolveProjectDir() → assertSafeProjectHookPath()
|
|
↓
|
|
assertClaudeAvailable() (spawnSync "claude --version")
|
|
↓
|
|
resolveConfiguredPet() → listPets() → pickPet() (interactive)
|
|
↓
|
|
prepareProjectLocalHooks() → Build hook command with marker
|
|
↓
|
|
runClaudeMcpAddJson() → spawnSync "claude mcp add-json ..."
|
|
↓
|
|
writePreparedHooks() → Atomic write to .claude/settings.local.json
|
|
|
|
familiaros configure --agent cursor --with-rules
|
|
↓
|
|
readCursorMcpConfig() → classifyCursorMcpStatus()
|
|
↓
|
|
readCursorFamiliarOSRules() → classifyCursorRulesStatus()
|
|
↓
|
|
planCursorMcpInstall/Replace() → executeCursorMcpWrite()
|
|
↓
|
|
planCursorRulesInstall/Replace() → executeCursorRulesWrite()
|
|
|
|
familiaros status
|
|
↓
|
|
createFamiliarOSClient().status() → Print JSON result
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
**Dependencies**:
|
|
- `@familiaros/client` - Familiar listing, installation, status, react, say
|
|
- `@familiaros/claude` - Hook management, MCP config
|
|
- `@familiaros/mcp` - MCP server spawning
|
|
- `@familiaros/opencode` - OpenCode project setup
|
|
- `@familiaros/cursor` - Cursor project setup (MCP + rules)
|
|
|
|
**External Commands**:
|
|
- `claude` - Claude Code CLI for MCP configuration
|
|
- `npx` - For published package execution
|
|
|
|
**Exports**:
|
|
- `cliPackageName` constant
|
|
- `configureProject()`, `resolveConfiguredPet()` - Programmatic API
|
|
- `parseConfigureArgs()`, `parseInstallArgs()`, `parseReactArgs()`, `parseSayArgs()` - Argument parsing
|
|
- `createVersionPinnedCliCommand()`, `createLocalDevCliCommand()` - Command builders
|
|
- `installProjectLocalHooks()`, `prepareProjectLocalHooks()` - Hook installation
|
|
- `runClaudeMcpAddJson()`, `createClaudeMcpAddJsonArgs()` - MCP integration
|