mudlet-ai-client/docs/WORKFLOW.md

Workflow di Sviluppo

Setup Ambiente

Prerequisiti

• Node.js 18+
• npm 9+
• Git

Installazione

# 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

# 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

# Build completo
npm run build

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

Debug

# 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:

import { EventEmitter } from 'events';

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

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

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

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:

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:

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:

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

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

IPC Communication Pattern

Request-Response (Renderer → Main)

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

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

Events (Main → Renderer)

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

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

Two-Way Communication

// 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

# 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

# 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:

### 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