# Workflow di Sviluppo

## Setup Ambiente

### Prerequisiti
- Node.js 18+
- npm 9+
- Git

### Installazione

```bash
# Clone repository
cd mudlet-ai-client

# Installa dipendenze
npm install

# Verifica installazione
npm run dev  # Vite dev server
npm start    # Electron app
```

### Struttura Rami

```
main
├── develop          # Branch di sviluppo attivo
├── feature/*        # Feature branches
├── bugfix/*         # Bug fix branches
└── release/*        # Release branches
```

## Workflow Git

### Feature Development

```bash
# Crea branch da develop
git checkout develop
git checkout -b feature/nome-feature

# Sviluppa e commit
git add .
git commit -m "feat: descrizione feature"

# Push e PR
git push origin feature/nome-feature
# Crea Pull Request su GitHub
```

### Commit Convention

```
<type>(<scope>): <description>

Types:
- feat: Nuova feature
- fix: Bug fix
- docs: Documentazione
- refactor: Code refactoring
- test: Aggiunta test
- chore: Manutenzione

Examples:
feat(telnet): add ANSI color support
fix(autoplayer): resolve action queue ordering
docs(api): update IPC documentation
```

## Build & Test

### Comandi NPM

| Comando | Descrizione |
|---------|-------------|
| `npm run dev` | Avvia Vite dev server (port 3000) |
| `npm run build` | Build production (compila TS + Vite) |
| `npm run preview` | Preview build production |
| `npm start` | Avvia Electron app |

### Build Production

```bash
# Build completo
npm run build

# Output in dist/
dist/
├── renderer/     # Bundle React
└── main/         # Bundle Electron main
```

### Debug

```bash
# DevTools aperto automaticamente
npm start

# Per debug remoto:
# 1. Apri DevTools (View → Toggle DevTools)
# 2. Console: renderer process
# 3. Terminale: main process (output console.log)
```

## Sviluppo Componenti

### Aggiungere Nuovo Servizio Main Process

1. Crea file in `src/main/services/NomeService.ts`:

```typescript
import { EventEmitter } from 'events';

interface NomeServiceEvents {
  'event': [data: Type];
}

export class NomeService extends EventEmitter<NomeServiceEvents> {
  // Implementazione
}
```

2. Aggiungi in `src/main/index.ts`:

```typescript
import { NomeService } from './services/NomeService';

const nomeService = new NomeService();

// IPC handlers
ipcMain.handle('nome-action', async (_, arg) => {
  return nomeService.action(arg);
});

// Event forwarding
nomeService.on('event', (data) => {
  if (mainWindow) {
    mainWindow.webContents.send('nome-event', data);
  }
});
```

3. Aggiorna `src/preload/index.js`:

```javascript
nomeAction: (arg) => ipcRenderer.invoke('nome-action', arg),
onNomeEvent: (callback) => ipcRenderer.on('nome-event', (_, data) => callback(data)),
```

### Aggiungere Componente UI

1. Crea file in `src/renderer/components/NomeComponente.tsx`:

```typescript
import { useState, useEffect } from 'react';

interface Props {
  prop1: string;
  onAction: (data: Type) => void;
}

export function NomeComponente({ prop1, onAction }: Props) {
  // Implementazione
  return <div>...</div>;
}
```

2. Importa in `App.tsx`:

```typescript
import { NomeComponente } from './components/NomeComponente';

// Usa nel render
<NomeComponente prop1="value" onAction={handler} />
```

## IPC Communication Pattern

### Request-Response (Renderer → Main)

```typescript
// Renderer
const result = await window.electronAPI.someAction(arg);

// Main
ipcMain.handle('some-action', async (_, arg) => {
  return service.action(arg);
});
```

### Events (Main → Renderer)

```typescript
// Renderer
window.electronAPI.onSomeEvent((data) => {
  console.log(data);
});

// Main
service.on('event', (data) => {
  if (mainWindow) {
    mainWindow.webContents.send('someEvent', data);
  }
});
```

### Two-Way Communication

```typescript
// 1. Renderer invia richiesta
const action = await window.electronAPI.getDecision(context);

// 2. Main processa
ipcMain.handle('getDecision', async (_, context) => {
  return autoplayerService.decide(context);
});

// 3. Risultato tornato al renderer
```

## Testing

### Test Manuali

```bash
# 1. Avvia dev server
npm run dev

# 2. Avvia Electron (nuovo terminale)
npm start

# 3. Testa connessione
# - Host: 172.24.19.225
# - Porta: 6666

# 4. Testa autoplayer
# - Attiva toggle
# - Verifica decisioni
```

### Checklist Pre-Release

- [ ] TypeScript senza errori (`npm run build`)
- [ ] Componenti renderizzano correttamente
- [ ] Connessione Telnet funziona
- [ ] Ollama reachable e risponde
- [ ] Autoplayer genera azioni sensate
- [ ] No memory leaks (DevTools → Memory)
- [ ] UI responsive

## Deployment

### Electron Build

```bash
# Installa electron-builder
npm install electron-builder --save-dev

# Build per piattaforma corrente
npm run build
npx electron-builder

# Output in release/
```

### Update MUD_AUTOPLAYER_PLAN.md

Dopo ogni fase completata:

```markdown
### Fase N: Nome (DATA) - ✅ COMPLETATO
- [x] Task 1
- [x] Task 2
- [ ] Task 3 (futuro)
```

## Risorse

| Risorsa | URL |
|---------|-----|
| Electron Docs | https://www.electronjs.org/docs |
| React Docs | https://react.dev |
| TypeScript | https://www.typescriptlang.org/docs |
| Vite | https://vitejs.dev |
| Tailwind | https://tailwindcss.com/docs |
| Ollama API | https://github.com/ollama/ollama/blob/main/docs/api.md |