# Issue #89: [FED-006] COMMAND Message Type

## Objective

Implement COMMAND message type for federation to enable remote instances to execute commands on connected instances. This builds on the existing FederationMessage model and follows the patterns established by FED-005 (QUERY Message Type).

## Approach

### Design Decisions

1. **Reuse FederationMessage Model**: The Prisma schema already supports COMMAND type in the FederationMessageType enum
2. **Follow Query Pattern**: Mirror the structure and flow of QueryService/QueryController for consistency
3. **Command Authorization**: Add authorization checks to ensure only permitted commands can be executed
4. **Command Types**: Support various command types (e.g., spawn_agent, update_config, etc.)

### Architecture

```
CommandService
├── sendCommand() - Send command to remote instance
├── handleIncomingCommand() - Process incoming command
├── processCommandResponse() - Handle command response
├── getCommandMessages() - List commands for workspace
└── getCommandMessage() - Get single command details

CommandController
├── POST /api/v1/federation/command - Send command
├── POST /api/v1/federation/incoming/command - Handle incoming command
├── GET /api/v1/federation/commands - List commands
└── GET /api/v1/federation/commands/:id - Get command details
```

### Command Message Structure

```typescript
interface CommandMessage {
  messageId: string; // Unique identifier
  instanceId: string; // Sending instance
  commandType: string; // Command type (spawn_agent, etc.)
  payload: Record<string, unknown>; // Command-specific data
  timestamp: number; // Unix milliseconds
  signature: string; // RSA signature
}

interface CommandResponse {
  messageId: string; // Response identifier
  correlationId: string; // Original command messageId
  instanceId: string; // Responding instance
  success: boolean; // Command execution result
  data?: unknown; // Result data
  error?: string; // Error message
  timestamp: number; // Unix milliseconds
  signature: string; // RSA signature
}
```

## Progress

### Phase 1: Types and DTOs (TDD)

- [x] Create command message types in message.types.ts
- [x] Create command DTOs (SendCommandDto, IncomingCommandDto)
- [x] Updated Prisma schema to add commandType and payload fields

### Phase 2: Command Service (TDD)

- [x] Write tests for CommandService.sendCommand()
- [x] Implement sendCommand()
- [x] Write tests for CommandService.handleIncomingCommand()
- [x] Implement handleIncomingCommand()
- [x] Write tests for CommandService.processCommandResponse()
- [x] Implement processCommandResponse()
- [x] Write tests for query methods (getCommandMessages, getCommandMessage)
- [x] Implement query methods

### Phase 3: Command Controller (TDD)

- [x] Write tests for CommandController endpoints
- [x] Implement CommandController
- [x] Add controller to FederationModule

### Phase 4: Integration

- [x] All unit tests passing (23 tests)
- [x] Signature verification implemented
- [x] Authorization checks implemented
- [x] Error handling tested

### Test Results

- **CommandService**: 90.21% coverage (15 tests, all passing)
- **CommandController**: 100% coverage (8 tests, all passing)
- **Total**: 23 tests, all passing

### Remaining Tasks

- [ ] Run Prisma migration to create commandType and payload columns
- [ ] Generate Prisma client with new schema
- [ ] Manual integration testing with live instances

## Testing Strategy

### Unit Tests

- DTO validation
- CommandService methods (mocked dependencies)
- CommandController endpoints (mocked service)

### Integration Tests

- Full command send/receive cycle
- Signature verification
- Error scenarios
- Authorization checks

### Coverage Target

- Minimum 85% code coverage
- All error paths tested
- All validation rules tested

## Security Considerations

1. **Signature Verification**: All incoming commands must be signed
2. **Authorization**: Check if sending instance has permission for command type
3. **Timestamp Validation**: Reject commands with old timestamps
4. **Rate Limiting**: Consider adding rate limits (future enhancement)
5. **Command Whitelist**: Only allow specific command types

## Notes

### Reusable Patterns from QueryService

- Signature verification flow
- Connection validation
- Message storage in FederationMessage table
- Response correlation via correlationId
- Status tracking (PENDING, DELIVERED, FAILED)

### Key Differences from QUERY

- Commands modify state (queries are read-only)
- Commands require stricter authorization
- Command types need to be registered/whitelisted
- Command execution is async (may take longer than queries)

### Future Enhancements

- Command queueing for offline instances
- Command retry logic
- Command expiration
- Command priority levels