# Claude Code Assistant Rules - Desktop App

# Always verify your work before saying its completed. Check for errors and edge cases. Ensure in a production environment that the solution works end to end, not just in mocked tests.

# NEVER WRITE AI SLOP. YOUR CODE MUST BE PERFECT. IT MUST NOT LOOK LIKE AI GENERATED CODE.

## Code Style Guidelines

1. **Comments Policy**: Never write inline code comments, always add JSDoc comments to the top of functions or classes. JSDocs should have human-readable descriptions of the function or class that anyone can understand simply as well as type definitions for the parameters and return values.

2. **DRY Principle**: Keep code DRY. Prioritize reusability and maintain small, focused components. Before creating new functions/components, search the codebase for existing similar implementations. Always reuse existing utilities, helpers, and components when available.

3. **React Best Practices**:
   - Never write JSX code inside functions like "renderContent" - create child components instead
   - Avoid inline functions for rendering React components - use named child components or inline JSX only
   - Never use inline callbacks when passing props to components
   - Never call hooks inside loops, conditionals, or maps - follow React Hook rules strictly

4. **TypeScript**:
   - Always add thoughtful, well-scoped TypeScript types at the top of the file or in a separate file
   - Define a separate Prop type for every React component
   - Place all custom types at the top of the file or in a shared types.ts file

5. **Code Quality**:
   - Ensure zero syntax errors, especially in JSX
   - Code must be well-formatted (Prettier-compliant)
   - Remove all trailing spaces
   - Fix all ESLint and TypeScript errors - no exceptions

6. **Icons**: Always use react-icons instead of inline SVGs for icons.

7. **Component Styling**: When customizing styles on shadcn components (e.g., Button), extend with props instead of hardcoding styles.

8. **Tailwind CSS**: Never hardcode color values in Tailwind - define them in the Tailwind config.

9. **Typography**: Always use the Typography component for `<p>`, `<h1>`, etc. Avoid raw HTML tags.

10. **Database Access**: Always use Drizzle ORM for database operations. Never write raw SQL queries. The desktop app uses Drizzle with SQLite schema defined in src/main/db/schema.ts.

## Debug Logging

The desktop application includes comprehensive logging for development debugging:

- **Command**: `pnpm run dev:log` - Runs development server with full logging
- **Port**: Uses port 5174 (instead of 5173) to avoid conflicts with regular `dev` command
- **Concurrent Usage**: Can run alongside regular dev server without port conflicts
- **Log File**: `dev.log` - Contains all stdout/stderr with timestamps
- **Log Backup**: `dev.prev.log` - Previous run's log file
- **Format**: Timestamped entries in clean text format (ANSI codes stripped)

### Port Usage
- **Standard Dev**: `pnpm run dev` uses port 5173
- **Logging Dev**: `pnpm run dev:log` uses port 5174
- **Port Information**: Logged in the header when the server starts

This logging is particularly useful for Claude and other agents to analyze:
- Application startup issues
- Runtime errors and exceptions
- Environment configuration problems
- Electron Forge build processes

Use `pnpm run dev:log` when you need to capture debug information for analysis.

## Playwright MCP Automation

The desktop app now has fully functional Playwright automation for testing and debugging:

### Environment Setup Requirements
1. **Environment Variables**: Must have `.env` file in desktop directory with:
   ```bash
   HEDERA_OPERATOR_ID=0.0.YOUR_ACCOUNT
   HEDERA_OPERATOR_KEY=your-private-key
   HEDERA_NETWORK=testnet
   OPENAI_API_KEY=your-openai-key
   ANTHROPIC_API_KEY=your-anthropic-key
   ```

2. **Build Required**: App must be built before Playwright testing:
   ```bash
   pnpm run build
   ```

### Available Test Scripts
- **`scripts/test-functional-chat-flow.ts`** - Full end-to-end testing with credential validation
- **`scripts/test-app-launch-simple.ts`** - Basic app launch verification  
- **`scripts/playwright-automation.ts`** - Core automation functions
- **`scripts/playwright-mcp-interface.ts`** - MCP command interface

### Key Features Working
✅ **Automatic Credential Loading**: Environment variables loaded via dotenv  
✅ **Privacy Policy Handling**: Automatically accepts terms/privacy policy  
✅ **Navigation Support**: Dashboard → Personal Assistant → Chat interface  
✅ **Setup Detection**: Identifies when initial app configuration required  
✅ **Configuration Bypass**: No "Get Started" screen when env vars present  

### Current Status
- **Working**: Environment variable injection, credential validation, app launch, privacy policy acceptance, navigation to chat interface
- **In Progress**: Agent initialization optimization (currently 60s timeout)

### Quick Test Commands
```bash
# Basic launch verification
npx tsx scripts/test-app-launch-simple.ts

# Full end-to-end testing
npx tsx scripts/test-functional-chat-flow.ts
```

### Debugging Integration
- **Logging**: All test scripts integrate with `dev.log` for comprehensive debugging
- **Screenshots**: Automatic screenshots saved during test failures
- **Error Detection**: Comprehensive UI error state detection
- **Performance**: Timing and performance metrics captured

## Desktop-Specific Guidelines

1. **Electron Architecture**: Follow main/renderer/preload separation patterns
2. **IPC Communication**: Use typed IPC handlers defined in src/main/ipc/
3. **State Management**: Use Zustand stores for global state management
4. **Services**: Place business logic in src/main/services/
5. **Database**: All data persistence through Drizzle ORM and SQLite

## Communication Guidelines

- Keep responses short and to the point
- Output is more important than explanations
- Be concise and direct in all communications

## Project-Specific Commands

When working on the desktop app, always check for and run:

- `pnpm run lint` - ESLint checks
- `pnpm run typecheck` - TypeScript type checking
- `pnpm run test` - Jest test suite
- `pnpm run dev` - Standard development server
- `pnpm run dev:log` - Development server with logging

## Package Management

- Always use pnpm for package management
- Never install packages without checking existing dependencies first

## Testing Guidelines

- Use Jest with @swc/jest for testing
- Follow the existing test structure in __tests__/
- Write integration tests for IPC communication
- Test Electron main/renderer boundaries

## Package Dependency Chain and Rebuild Process

When fixing bugs or adding features that span multiple packages in this project, follow this **MANDATORY** rebuild and reinstall chain to ensure changes propagate correctly:

### 1. Standards-Agent-Kit Changes
```bash
cd /Users/michaelkantor/CascadeProjects/hashgraph-online/standards-agent-kit
pnpm run build
```

### 2. Install SAK in Conversational-Agent
```bash
cd /Users/michaelkantor/CascadeProjects/hashgraph-online/conversational-agent
pnpm install @hashgraphonline/standards-agent-kit@latest
pnpm run build
```

### 3. Install Conversational-Agent in Desktop
```bash
cd /Users/michaelkantor/CascadeProjects/hashgraph-online/desktop
pnpm install @hashgraphonline/conversational-agent@latest
```

### 4. Test the Complete Chain
```bash
cd /Users/michaelkantor/CascadeProjects/hashgraph-online/desktop
npx tsx scripts/test-form-submission-fix.ts
```

**Critical Notes:**
- **ALWAYS** follow this exact sequence when changes affect multiple packages
- **NEVER** skip steps - each package must be rebuilt before the next installation
- **VERIFY** each step completes successfully before proceeding
- Changes in `standards-agent-kit` affect `conversational-agent` which affects `desktop`
- This chain is essential for form submission, schema validation, and tool execution fixes

### Debugging Chain Issues
If the chain rebuild fails:
1. Check for TypeScript errors in each package during build
2. Verify package.json dependencies are correct
3. Clear node_modules and reinstall if needed: `rm -rf node_modules pnpm-lock.yaml && pnpm install`
4. Use `pnpm ls @hashgraphonline/package-name` to verify version installation

This dependency chain management is crucial for maintaining the desktop app's integration with the underlying agent frameworks.

These rules ensure consistent, high-quality code that follows the desktop app's established patterns and best practices.