openpetswithchatandmcp/packages/cursor/codemap.md

Package: @familiaros/cursor

Responsibility

Pure Node.js package for Cursor editor integration file management. Manages FamiliarOS MCP entries in Cursor's mcp.json configuration files and optional project-local Cursor rules guidance. Provides safe, atomic file operations with validation, backup, and redaction capabilities.

Design/Patterns

Config Path Resolution

• Global config: <homeDir>/.cursor/mcp.json - user-wide MCP settings
• Project config: <projectDir>/.cursor/mcp.json - project-specific MCP settings
• Rules path: <projectDir>/.cursor/rules/familiaros.mdc - project-local Cursor rules
• All APIs accept explicit configPath for custom locations

Safety-First File Operations

• Strict JSON only (no JSONC comments)
• Maximum config size: 256 KiB (rules: 64 KiB)
• Reject symlinks at any path level (config file, parent directories, ancestors)
• Reject non-regular files (directories, sockets, etc.)
• Validate parent directories before creating .cursor folders
• Atomic writes using temp files and atomic rename
• Automatic backup creation before modifications
• Private file permissions (0o600) where supported

Status Classification (MCP & Rules)

• missing: No config file or no FamiliarOS entry exists
• installed: Matching FamiliarOS entry present and up-to-date
• needs-update: Old version, different familiar, or content drift
• conflict: Non-FamiliarOS entry blocking installation
• invalid: Parse error, oversized, unsafe path, malformed schema
• error: Unexpected I/O failure

MCP Entry Format

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@familiaros/mcp@VERSION", "--familiar", "PET_ID"]
}

Managed Entry Detection

• Published mode: npx -y @familiaros/mcp@SEMVER [--familiar PET]
• Local mode: node <absolute-path> [--familiar PET]
• Validates semantic versioning and familiar ID format
• Rejects unpinned versions (e.g., @latest)

Sensitive Data Redaction

Recursive, case-insensitive redaction of:

• Keys: env, headers, auth, authorization, token, secret, password, credentials
• URL query parameters matching sensitive patterns
• String values containing token=, api_key=, secret=, password=, auth=

Cursor Rules Management

• Exact whole-file ownership requires recognized frontmatter
• Requires exactly one ordered FAMILIAROS:CURSOR_RULES:START/END marker pair
• Rejects duplicate, reversed, or missing markers
• Rejects user content before/after managed block
• Desktop uses preview/copy only; CLI writes project-local rules

Flow

MCP Installation Flow

1. Read existing config via readCursorMcpConfig(path)
2. Classify status via classifyCursorMcpStatus(result, path, expected)
3. Plan operation via planCursorMcpInstall(path, options, allowReplace?)
4. Execute write via executeCursorMcpWrite(plan)
5. Atomic write creates temp file, backs up existing, renames to target

MCP Replacement Flow

1. Read and classify existing config
2. Verify status is needs-update, conflict, or installed
3. Plan replace via planCursorMcpReplace(path, options)
4. Execute preserves unrelated MCP servers and top-level fields

MCP Removal Flow

1. Read and classify existing config
2. Verify entry is managed by FamiliarOS (not conflict)
3. Plan remove via planCursorMcpRemove(path)
4. Execute removes only mcpServers.familiaros, preserves other servers
5. Empty mcpServers kept as {} after removal

Rules Installation Flow

1. Read existing rules via readCursorFamiliarOSRules(projectDir)
2. Classify status via classifyCursorRulesStatus(result, path, expected?)
3. Plan via planCursorRulesInstall(projectDir, allowReplace?)
4. Execute via executeCursorRulesWrite(plan)
5. Managed content includes frontmatter + START/END markers

Preview/Redaction Flow

1. Build preview via buildFamiliarOSOnlyPreview(options)
2. Redact sensitive config via redactCursorConfig(config)
3. Safe for logging and UI display

Integration

Entry Points

• src/index.ts: Public API exports (re-exports all modules)
• src/cursor-mcp.ts: MCP entry builders and path utilities
• src/cursor-status.ts: Status classification and config read/write operations
• src/cursor-previews.ts: Config preview and redaction helpers
• src/cursor-rules.ts: Project-local Cursor rules preview/status/write/remove helpers
• src/check-cursor.ts: Contract validation tests (runs via npm test)

Exported APIs

From cursor-mcp.ts:

• buildCursorMcpEntry(options): Build MCP entry object
• formatCursorMcpConfig(options): Build full config with familiaros entry
• getCursorGlobalMcpPath(homeDir): Get global config path
• getCursorProjectMcpPath(projectDir): Get project config path
• validateFamiliarOSPetId(id): Validate and return familiar ID
• isValidPetId(id): Check if familiar ID is valid

From cursor-status.ts:

• classifyCursorMcpStatus(result, path, expected): Classify config status
• readCursorMcpConfig(path): Read and validate config file
• planCursorMcpInstall(path, options, allowReplace?): Plan install operation
• planCursorMcpReplace(path, options): Plan replace operation
• planCursorMcpRemove(path): Plan remove operation
• executeCursorMcpWrite(plan): Execute planned write atomically
• isManagedFamiliarOSMcpEntry(value): Check if entry is FamiliarOS-managed
• maxCursorConfigBytes: 256 KiB limit constant

From cursor-previews.ts:

• buildFamiliarOSOnlyPreview(options): Build FamiliarOS-only preview
• redactCursorConfig(config): Redact sensitive fields from config

From cursor-rules.ts:

• getCursorProjectRulesPath(projectDir): Get project rules path
• buildCursorFamiliarOSRule(): Build managed Cursor rules content
• buildCursorRulesPreview(): Build copyable rules preview
• readCursorFamiliarOSRules(projectDir): Safely read managed rules file
• classifyCursorRulesStatus(result, path, expected?): Classify rules status
• planCursorRulesInstall(projectDir, allowReplace?): Plan project rules install/update
• planCursorRulesReplace(projectDir): Plan explicit replacement
• planCursorRulesRemove(projectDir): Plan managed rules removal
• executeCursorRulesWrite(plan): Execute rules write/remove atomically
• isManagedCursorFamiliarOSRule(content): Check managed marker/frontmatter shape
• maxCursorRulesBytes: 64 KiB limit constant

Package Scripts

• npm test: Run contract validation tests (node dist/check-cursor.js)
• npm run check: Full typecheck + build + test pipeline
• npm run typecheck: TypeScript type checking only
• npm run build: Compile TypeScript to dist/

Downstream Consumers

• Desktop app: Uses preview/redaction APIs for UI display
• CLI tools: Uses planning/execution APIs for install/remove operations
• Both use status classification to determine available actions

Test Coverage

check-cursor.ts validates:

• Familiar ID validation (valid/invalid patterns, length limits)
• MCP entry building (published/local modes, version validation)
• Config formatting and path helpers
• All status classifications (missing, empty, installed, needs-update, conflict, invalid)
• Parse errors, oversized files, symlink rejection
• Non-object schema rejection (top-level, mcpServers, entries)
• Backup creation and atomic write behavior
• Uninstall preserves unrelated entries and top-level fields
• No writes on invalid/error status
• No conflict write without explicit replace
• Explicit replace preserves unrelated servers/fields
• Recursive and case-insensitive redaction
• URL token parameter redaction
• Symlink parent/ancestor rejection
• Empty mcpServers preservation after remove
• Cursor project rules generation and path resolution
• Rules missing/installed/needs-update/conflict classification
• Rules duplicate/reversed/missing marker handling
• Rules frontmatter conflict detection
• Rules symlink parent/file, dangling symlink, non-regular, oversized rejection
• Rules backup, atomic write, replace, remove, and no-write invalid behavior