Skip to content

codemap.md

Latest commit

 

History

History
91 lines (72 loc) · 4.09 KB

codemap.md

File metadata and controls

91 lines (72 loc) · 4.09 KB
Raw

packages/cli/src/

TypeScript source files for the OpenPets CLI.

Files

index.ts

Main CLI entry point. Command routing, argument parsing, project configuration, plugin scaffolding/validation command dispatch, and all CLI operations.

Commands:

  • install <pet-id> - Install pet via running desktop app
  • configure - Interactive project setup for Claude, OpenCode, or Cursor
  • status - Check OpenPets desktop app connectivity
  • pets - List installed pets
  • react <reaction> - Send reaction to desktop app
  • say <message> [--reaction <reaction>] - Display message on pet
  • mcp [--pet <id>] - Spawn MCP server wrapper
  • hook - Execute Claude hook from stdin
  • plugin validate <dir> - Validate a local plugin manifest/package boundary
  • plugin new <name> --template <blank|reminder|ambient|ai-chat|tamagotchi|calendar> - Scaffold an SDK v3 plugin package

Configuration Flow:

  • configureProject() - Main entry for project setup
  • configureCursorProject() - Cursor MCP + rules configuration
  • configureOpenCodeProject() - OpenCode config setup
  • Claude: Hook settings + MCP via claude mcp add-json

Safety Checks:

  • resolveProjectDir() - Symlink/escape validation
  • assertSafeProjectHookPath() - .claude directory safety
  • assertClaudeAvailable() - Claude CLI presence check
  • Atomic file writes with temp + rename pattern

Exports:

  • cliPackageName - Package identifier constant
  • configureProject(), resolveConfiguredPet() - Programmatic API
  • parseConfigureArgs(), parseInstallArgs(), parseReactArgs(), parseSayArgs() and plugin command parsers - Argument parsers
  • createVersionPinnedCliCommand(), createLocalDevCliCommand() - Command builders
  • installProjectLocalHooks(), prepareProjectLocalHooks() - Hook installation
  • runClaudeMcpAddJson(), createClaudeMcpAddJsonArgs() - MCP integration

plugin-templates.ts

SDK v3 plugin scaffolding templates for openpets plugin new.

Template responsibilities:

  • Defines PluginTemplateName, pluginTemplateNames, and template content generators.
  • Emits manifestVersion 3 plugin folders with index.js, test.js, README content, and optional locales/en.json.
  • Covers blank, reminder, ambient, ai-chat, tamagotchi, and calendar patterns using the published SDK/test harness.
  • Demonstrates current plugin APIs: localized $t: manifest refs, ctx.t, ctx.ui.alert, dynamic menu items, schedule reconciliation, storage, events, AI, and virtual-pet HUD/state loops.

plugin-validate.ts

Author-time plugin folder validator for openpets plugin validate <dir>.

Validation responsibilities:

  • Reads openpets.plugin.json and validates manifestVersion 1/2/3 boundaries.
  • Enforces reverse-DNS ids, semver versions, JavaScript entry paths, SDK version compatibility, duplicate permissions, and v3 permission names.
  • Validates config schema fields, including v3 date, secret, and sound field types.
  • Checks exact network hosts, declared assets (icons, images, svgs, sprites, sounds), allowed extensions, size caps, panels, and safe relative file paths.
  • Mirrors desktop install-time validation while keeping the desktop runtime authoritative.

check-cli-contract.ts

Contract validation and integration checks. Runtime assertions for CLI behavior.

Test Coverage:

  • Argument parsing validation for all commands
  • Command builder output verification
  • Pet resolution (explicit vs interactive)
  • Project hook installation and updates
  • Claude MCP integration (mocked)
  • OpenCode project configuration scenarios
  • Cursor project configuration (MCP + rules)
  • Error handling and edge cases

Safety Tests:

  • Symlink detection and rejection
  • Path traversal prevention
  • Settings file atomic writes
  • Backup creation verification

Integration Tests:

  • OpenCode: Top-level vs .opencode/ config precedence
  • OpenCode: Existing config preservation
  • OpenCode: Custom MCP conflict detection
  • Cursor: MCP config installation
  • Cursor: Rules-only and remove-rules modes
  • Cursor: Conflict detection with --force
  • Plugin command parser, template scaffolding, and plugin validator boundary checks