Initial commit

2025-11-30 09:01:56 +08:00
commit 324f1d386c
21 changed files with 8327 additions and 0 deletions
--- a/commands/toduba-update-docs.md
+++ b/commands/toduba-update-docs.md
@@ -0,0 +1,607 @@
+---
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+argument-hint: "[--check] [--full] [--smart] [--service <name>] [--format md|html|json|pdf]"
+description: "Smart incremental updates con cache e multiple export formats per struttura gerarchica V2.0"
+---
+
+# Toduba Update Docs V2.0 - Smart Incremental Updates 🔄
+
+## Obiettivo
+
+Aggiornamento intelligente e incrementale della documentazione gerarchica V2.0 (docs/global, docs/services/, docs/operations/) con cache, change detection avanzata e supporto per multiple export formats.
+
+## Argomenti
+
+- `--check`: Mostra cosa verrebbe aggiornato senza modificare
+- `--full`: Forza rigenerazione completa (equivalente a toduba-init --force)
+- `--smart`: Abilita cache e ottimizzazioni AI (default: on)
+- `--service <name>`: Aggiorna solo documentazione per il servizio specificato
+- `--format`: Formato export (md, html, json, pdf) - default: md
+
+Argomenti ricevuti: $ARGUMENTS
+
+## Nuova Struttura Supportata (V2.0)
+
+```
+docs/
+├── .toduba-meta/              # Metadata e tracking
+│   ├── project-type.json
+│   ├── services.json
+│   ├── last-update.json
+│   └── service_*.json
+│
+├── global/                    # Documentazione globale
+│   ├── README.md
+│   ├── ARCHITECTURE.md
+│   ├── SETUP.md
+│   ├── CONTRIBUTING.md
+│   └── adr/
+│
+├── services/                  # Per-service documentation
+│   └── [service-name]/
+│       ├── README.md
+│       ├── SETUP.md
+│       ├── ARCHITECTURE.md
+│       ├── TECH-STACK.md
+│       ├── STYLE-GUIDE.md
+│       ├── ENDPOINTS.md (condizionale)
+│       ├── DATABASE.md (condizionale)
+│       ├── TESTING.md
+│       └── TROUBLESHOOTING.md
+│
+└── operations/                # DevOps docs
+    ├── DEPLOYMENT.md
+    ├── CI-CD.md
+    ├── MONITORING.md
+    ├── SECURITY.md
+    └── ENVIRONMENT-VARS.md
+```
+
+## Pre-requisiti
+
+```bash
+# Verifica che docs/ esista
+if [ ! -d "docs" ]; then
+  echo "❌ Errore: Documentazione non trovata!"
+  echo "   Esegui prima: /toduba-system:toduba-init"
+  exit 1
+fi
+
+# Verifica nuova struttura V2.0
+if [ ! -d "docs/.toduba-meta" ]; then
+  echo "⚠️ Struttura documentazione V1.0 rilevata!"
+  echo "   Aggiorna alla V2.0 con: /toduba-system:toduba-init --force"
+  echo "   (La vecchia documentazione verrà backuppata automaticamente)"
+  exit 1
+fi
+
+# Verifica metadata essenziali
+if [ ! -f "docs/.toduba-meta/last-update.json" ]; then
+  echo "⚠️ Metadata mancante - rigenerazione completa necessaria"
+  echo "   Esegui: /toduba-system:toduba-init --force"
+  exit 1
+fi
+```
+
+## Processo di Aggiornamento Intelligente V2.0
+
+### Fase 1: Analisi Cambiamenti (Struttura Gerarchica)
+
+#### 1.1 Lettura Stato Precedente
+
+```bash
+# Leggi metadata V2.0
+LAST_COMMIT=$(cat docs/.toduba-meta/last-update.json | grep -o '"git_commit": *"[^"]*"' | cut -d'"' -f4)
+LAST_UPDATE=$(cat docs/.toduba-meta/last-update.json | grep -o '"timestamp": *"[^"]*"' | cut -d'"' -f4)
+PROJECT_TYPE=$(cat docs/.toduba-meta/project-type.json | grep -o '"type": *"[^"]*"' | cut -d'"' -f4)
+
+# Leggi lista servizi
+SERVICES_LIST=$(cat docs/.toduba-meta/services.json | grep -o '"name": *"[^"]*"' | cut -d'"' -f4)
+
+echo "📊 Stato precedente:"
+echo "   • Ultimo aggiornamento: $LAST_UPDATE"
+echo "   • Ultimo commit: ${LAST_COMMIT:0:7}"
+echo "   • Tipo progetto: $PROJECT_TYPE"
+echo "   • Servizi: $(echo "$SERVICES_LIST" | wc -l)"
+```
+
+#### 1.2 Calcolo Differenze
+
+```bash
+# Commits dal'ultimo update
+COMMITS_COUNT=$(git rev-list --count ${LAST_COMMIT}..HEAD)
+
+# File modificati raggruppati per categoria
+git diff --name-only ${LAST_COMMIT}..HEAD | while read file; do
+  case "$file" in
+    */api/* | */routes/* | */controllers/*)
+      echo "API: $file" >> changes_api.txt
+      ;;
+    */components/* | */pages/* | */views/*)
+      echo "FRONTEND: $file" >> changes_frontend.txt
+      ;;
+    */models/* | */schemas/* | */migrations/*)
+      echo "DATABASE: $file" >> changes_db.txt
+      ;;
+    *.test.* | *.spec.* | */tests/*)
+      echo "TESTS: $file" >> changes_tests.txt
+      ;;
+  esac
+done
+```
+
+### Fase 2: Decisione Aggiornamento (Struttura Gerarchica V2.0)
+
+#### Matrice di Update per Struttura V2.0:
+
+```
+Cambiamenti rilevati → Documenti da aggiornare
+────────────────────────────────────────────────────────
+GLOBAL SCOPE:
+- Root files changes          → docs/global/README.md
+- Architecture changes        → docs/global/ARCHITECTURE.md
+- Contributing changes        → docs/global/CONTRIBUTING.md
+- Setup changes (monorepo)    → docs/global/SETUP.md
+
+SERVICE SCOPE (per ogni servizio modificato):
+- Source code changes         → docs/services/[name]/ARCHITECTURE.md
+- API/Routes changes          → docs/services/[name]/ENDPOINTS.md
+- Database/models changes     → docs/services/[name]/DATABASE.md
+- Dependencies changes        → docs/services/[name]/TECH-STACK.md
+- Test changes               → docs/services/[name]/TESTING.md
+- Style/conventions          → docs/services/[name]/STYLE-GUIDE.md
+- Any service changes        → docs/services/[name]/README.md
+
+OPERATIONS SCOPE:
+- CI/CD config changes        → docs/operations/CI-CD.md
+- Deployment scripts         → docs/operations/DEPLOYMENT.md
+- Monitoring config          → docs/operations/MONITORING.md
+- Security policies          → docs/operations/SECURITY.md
+- Env vars changes           → docs/operations/ENVIRONMENT-VARS.md
+
+METADATA (always):
+- docs/.toduba-meta/last-update.json
+- docs/.toduba-meta/service_*.json (se servizio modificato)
+```
+
+#### Rilevamento Servizio da File Modificato
+
+```bash
+detect_affected_service() {
+  local file_path="$1"
+
+  # Leggi servizi e i loro path
+  while IFS= read -r service_name; do
+    service_path=$(cat "docs/.toduba-meta/service_${service_name}.json" | grep -o '"path": *"[^"]*"' | cut -d'"' -f4)
+
+    # Se il file è nel path del servizio
+    if [[ "$file_path" == "$service_path"* ]]; then
+      echo "$service_name"
+      return
+    fi
+  done <<< "$SERVICES_LIST"
+
+  # Se non trovato, è probabilmente global
+  echo "global"
+}
+```
+
+#### Soglie per Update:
+
+- **Minor** (< 5 file): Aggiorna solo file specifici
+- **Medium** (5-20 file): Aggiorna categoria + INDEX
+- **Major** (> 20 file): Considera update completo
+- **Structural** (nuove cartelle/moduli): ARCHITECTURE.md obbligatorio
+
+### Fase 3: Update Incrementale
+
+#### 3.1 Per API_ENDPOINTS.md:
+
+```javascript
+// Analizza solo endpoint modificati
+const modifiedControllers = getModifiedFiles("controllers");
+const modifiedRoutes = getModifiedFiles("routes");
+
+// Estrai endpoint esistenti
+const existingEndpoints = parseExistingEndpoints("API_ENDPOINTS.md");
+
+// Analizza nuovi/modificati
+const updatedEndpoints = analyzeEndpoints(modifiedControllers, modifiedRoutes);
+
+// Merge intelligente
+const mergedEndpoints = mergeEndpoints(existingEndpoints, updatedEndpoints);
+
+// Rigenera solo sezioni cambiate
+updateSections("API_ENDPOINTS.md", mergedEndpoints);
+```
+
+#### 3.2 Per COMPONENTS.md:
+
+```javascript
+// Simile approccio per componenti UI
+const modifiedComponents = getModifiedFiles(["components", "pages"]);
+
+// Aggiorna solo componenti modificati
+for (const component of modifiedComponents) {
+  const componentDoc = generateComponentDoc(component);
+  replaceSection("COMPONENTS.md", component.name, componentDoc);
+}
+```
+
+#### 3.3 Per DATABASE_SCHEMA.md:
+
+```javascript
+// Rileva modifiche schema
+const schemaChanges = detectSchemaChanges();
+
+if (schemaChanges.migrations) {
+  appendSection(
+    "DATABASE_SCHEMA.md",
+    "## Migrazioni Recenti",
+    schemaChanges.migrations
+  );
+}
+
+if (schemaChanges.newModels) {
+  updateModelsSection("DATABASE_SCHEMA.md", schemaChanges.newModels);
+}
+```
+
+### Fase 4: Smart Merge Strategy
+
+#### Preservazione Contenuto Custom:
+
+```markdown
+<!-- TODUBA:START:AUTO -->
+
+[Contenuto generato automaticamente]
+
+<!-- TODUBA:END:AUTO -->
+
+<!-- TODUBA:CUSTOM:START -->
+
+[Contenuto custom preservato durante update]
+
+<!-- TODUBA:CUSTOM:END -->
+```
+
+#### Conflict Resolution:
+
+1. Preserva sempre sezioni custom
+2. Se conflitto in auto-generated:
+   - Backup versione vecchia
+   - Genera nuova
+   - Marca conflitti per review
+
+### Fase 5: Validazione e Report
+
+#### Se `--check`:
+
+```
+🔍 Toduba Update Docs - Analisi Cambiamenti
+
+📊 Sommario:
+- Commits dall'ultimo update: 15
+- File modificati: 23
+- Categorie impattate: API, Frontend, Tests
+
+📝 Documenti che verrebbero aggiornati:
+✓ INDEX.md (sempre aggiornato)
+✓ API_ENDPOINTS.md (8 endpoint modificati)
+✓ COMPONENTS.md (3 nuovi componenti)
+✓ TESTING.md (nuovi test aggiunti)
+○ DATABASE_SCHEMA.md (nessun cambiamento)
+○ ARCHITECTURE.md (nessun cambiamento strutturale)
+
+⏱️ Tempo stimato: ~8 secondi
+
+Esegui senza --check per applicare gli aggiornamenti.
+```
+
+#### Update Effettivo:
+
+```
+🔄 Toduba Update Docs - Aggiornamento in Corso...
+
+[===========----------] 55% Analizzando API changes...
+[==================---] 85% Aggiornando COMPONENTS.md...
+[====================] 100% Completato!
+
+✅ Documentazione Aggiornata con Successo!
+
+📊 Riepilogo Update:
+- File analizzati: 23
+- Documenti aggiornati: 4/10
+- Tempo impiegato: 7.3s
+- Risparmio vs regenerazione: ~45s
+
+📝 Modifiche applicate:
+✓ INDEX.md - Statistiche aggiornate
+✓ API_ENDPOINTS.md - 8 endpoint aggiornati, 2 nuovi
+✓ COMPONENTS.md - 3 nuovi componenti documentati
+✓ TESTING.md - Coverage aggiornato al 87%
+
+💾 metadata.json aggiornato:
+- last_updated: 2024-10-31T15:30:00Z
+- commits_since_generation: 0
+- git_info.last_commit: abc123def
+
+💡 Tip: Usa --check la prossima volta per preview
+```
+
+### Fase 6: Auto-Invocazione da Orchestrator
+
+Quando chiamato automaticamente:
+
+1. Sempre modalità silenziosa (no verbose)
+2. Log minimo solo se errori
+3. Return status code per orchestrator
+4. Se fallisce, non bloccare task principale
+
+## Ottimizzazioni Performance
+
+1. **Caching**: Cache analisi file per 5 minuti
+2. **Parallel Processing**: Analizza categorie in parallelo
+3. **Incremental Parsing**: Parse solo diff, non file interi
+4. **Smart Skip**: Skip file non documentabili (.test, .spec)
+5. **Batch Updates**: Accumula modifiche, scrivi una volta
+
+## Smart Incremental Updates (H1)
+
+### Cache System
+
+```typescript
+class DocumentationCache {
+  private cache = new Map();
+  private maxAge = 5 * 60 * 1000; // 5 minuti
+
+  async getAnalysis(filePath: string): Promise<Analysis | null> {
+    const cached = this.cache.get(filePath);
+    if (cached && Date.now() - cached.timestamp < this.maxAge) {
+      return cached.analysis;
+    }
+    return null;
+  }
+
+  setAnalysis(filePath: string, analysis: Analysis) {
+    this.cache.set(filePath, {
+      analysis,
+      timestamp: Date.now(),
+      hash: this.calculateHash(filePath),
+    });
+  }
+
+  async isValid(filePath: string): Promise<boolean> {
+    const cached = this.cache.get(filePath);
+    if (!cached) return false;
+
+    const currentHash = await this.calculateHash(filePath);
+    return cached.hash === currentHash;
+  }
+}
+```
+
+### Smart Change Detection
+
+```javascript
+// Usa git diff con analisi semantica
+const detectSmartChanges = async () => {
+  const changes = {
+    breaking: [],
+    feature: [],
+    bugfix: [],
+    refactor: [],
+    documentation: [],
+  };
+
+  // Analizza AST per determinare tipo di cambiamento
+  const diff = await git.diff("--cached", "--name-status");
+
+  for (const file of diff) {
+    const analysis = await analyzeFileChange(file);
+
+    // Categorizza in base al contenuto, non solo al path
+    if (analysis.breaksAPI) changes.breaking.push(file);
+    else if (analysis.addsFeature) changes.feature.push(file);
+    else if (analysis.fixesBug) changes.bugfix.push(file);
+    else if (analysis.refactors) changes.refactor.push(file);
+    else changes.documentation.push(file);
+  }
+
+  return changes;
+};
+```
+
+### Dependency Graph Updates
+
+```typescript
+// Aggiorna solo documenti dipendenti
+const updateDependentDocs = async (changedFile: string) => {
+  const dependencyGraph = await loadDependencyGraph();
+  const affected = dependencyGraph.getDependents(changedFile);
+
+  // Update solo documenti realmente impattati
+  for (const doc of affected) {
+    await updateSection(doc, changedFile);
+  }
+};
+```
+
+## Multiple Export Formats (H2)
+
+### Format Converters
+
+```typescript
+interface FormatConverter {
+  convert(markdown: string, options?: any): string | Buffer;
+  extension: string;
+  mimeType: string;
+}
+
+const converters: Record<string, FormatConverter> = {
+  html: {
+    convert: (md) => {
+      const html = marked.parse(md);
+      return `
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Toduba Documentation</title>
+  <link rel="stylesheet" href="toduba-docs.css">
+</head>
+<body>${html}</body>
+</html>`;
+    },
+    extension: ".html",
+    mimeType: "text/html",
+  },
+
+  json: {
+    convert: (md) => {
+      const sections = parseMarkdownToSections(md);
+      return JSON.stringify(
+        {
+          version: "2.0.0",
+          generated: new Date().toISOString(),
+          sections,
+          metadata: getMetadata(),
+        },
+        null,
+        2
+      );
+    },
+    extension: ".json",
+    mimeType: "application/json",
+  },
+
+  pdf: {
+    convert: async (md) => {
+      // Usa markdown-pdf o puppeteer
+      const html = marked.parse(md);
+      return await generatePDF(html);
+    },
+    extension: ".pdf",
+    mimeType: "application/pdf",
+  },
+};
+```
+
+### Export Pipeline
+
+```javascript
+const exportDocumentation = async (format: string = "md") => {
+  const converter = converters[format];
+  if (!converter) throw new Error(`Format ${format} not supported`);
+
+  // Crea directory per formato
+  const outputDir = `docs/export/${format}`;
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // Converti tutti i documenti
+  for (const file of await glob("docs/*.md")) {
+    const content = await fs.readFile(file, "utf8");
+    const converted = await converter.convert(content);
+
+    const outputName = path.basename(file, ".md") + converter.extension;
+    await fs.writeFile(`${outputDir}/${outputName}`, converted);
+  }
+
+  console.log(`✅ Exported to ${outputDir}/`);
+};
+```
+
+### Format-Specific Templates
+
+```typescript
+// Templates per diversi formati
+const templates = {
+  html: {
+    css: `
+      .toduba-docs {
+        font-family: 'Inter', sans-serif;
+        max-width: 1200px;
+        margin: 0 auto;
+      }
+      .sidebar { position: fixed; left: 0; width: 250px; }
+      .content { margin-left: 270px; }
+      .code-block { background: #f4f4f4; padding: 1rem; }
+    `,
+  },
+
+  pdf: {
+    pageSize: "A4",
+    margins: { top: "2cm", bottom: "2cm", left: "2cm", right: "2cm" },
+    header: "🤖 Toduba Documentation",
+    footer: "Page {page} of {pages}",
+  },
+};
+```
+
+## Gestione Errori
+
+- **Metadata corrotto**: Fallback a rigenerazione
+- **Git history perso**: Usa timestamp per determinare modifiche
+- **Conflitti merge**: Crea .backup e procedi
+- **Docs readonly**: Alert user, skip update
+- **Out of sync**: Se > 100 commits, suggerisci --full
+- **Cache invalido**: Invalida e rigenera
+- **Export fallito**: Mantieni formato originale
+
+## Performance Metrics
+
+```
+📊 Smart Update Performance:
+- Cache hit rate: 75%
+- Average update time: 3.2s (vs 45s full)
+- Memory usage: -60% con streaming
+- File I/O: -80% con cache
+```
+
+## Integrazione con Orchestrator
+
+L'orchestrator invoca automaticamente quando:
+
+```javascript
+if (modifiedFiles > 10 || majorRefactoring || newModules) {
+  await invokeCommand("toduba-update-docs --smart");
+}
+```
+
+Non viene invocato per:
+
+- Modifiche a singoli file
+- Fix di typo/commenti
+- Modifiche solo a test
+- Operazioni di configurazione
+
+## Output con Multiple Formats
+
+```
+🔄 Toduba Smart Update - Multiple Formats
+
+📊 Analisi Smart:
+- Cache hits: 18/23 (78%)
+- Semantic changes detected: 5
+- Affected documents: 3
+
+📝 Generazione formati:
+[====] MD: ✅ 100% (base format)
+[====] HTML: ✅ 100% (con styling)
+[====] JSON: ✅ 100% (structured data)
+[====] PDF: ✅ 100% (print-ready)
+
+✅ Export completato:
+- docs/export/html/
+- docs/export/json/
+- docs/export/pdf/
+
+⚡ Performance:
+- Tempo totale: 4.8s
+- Risparmio: 89% vs full regeneration
+```