terra-hiven 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/LICENSE.md +20 -0
  2. package/README.md +233 -0
  3. package/assets/hiven_logo_v2.png +0 -0
  4. package/bin/hiven.js +225 -0
  5. package/console/.nojekyll +0 -0
  6. package/console/app.js +588 -0
  7. package/console/assets/hiven_logo_v2.png +0 -0
  8. package/console/data/swarms_history.json +38 -0
  9. package/console/index.html +694 -0
  10. package/console/style.css +1039 -0
  11. package/console/webbl.config.json +5 -0
  12. package/dist/api.d.ts +13 -0
  13. package/dist/api.d.ts.map +1 -0
  14. package/dist/api.js +142 -0
  15. package/dist/api.js.map +1 -0
  16. package/dist/honeycombs.d.ts +30 -0
  17. package/dist/honeycombs.d.ts.map +1 -0
  18. package/dist/honeycombs.js +221 -0
  19. package/dist/honeycombs.js.map +1 -0
  20. package/dist/index.d.ts +38 -0
  21. package/dist/index.d.ts.map +1 -0
  22. package/dist/index.js +133 -0
  23. package/dist/index.js.map +1 -0
  24. package/dist/inference.d.ts +33 -0
  25. package/dist/inference.d.ts.map +1 -0
  26. package/dist/inference.js +217 -0
  27. package/dist/inference.js.map +1 -0
  28. package/dist/server.d.ts +10 -0
  29. package/dist/server.d.ts.map +1 -0
  30. package/dist/server.js +54 -0
  31. package/dist/server.js.map +1 -0
  32. package/dist/swarm.d.ts +30 -0
  33. package/dist/swarm.d.ts.map +1 -0
  34. package/dist/swarm.js +196 -0
  35. package/dist/swarm.js.map +1 -0
  36. package/dist/types.d.ts +117 -0
  37. package/dist/types.d.ts.map +1 -0
  38. package/dist/types.js +6 -0
  39. package/dist/types.js.map +1 -0
  40. package/dist/vault.d.ts +19 -0
  41. package/dist/vault.d.ts.map +1 -0
  42. package/dist/vault.js +99 -0
  43. package/dist/vault.js.map +1 -0
  44. package/package.json +63 -0
  45. package/templates/.github/workflows/swarm.yml +229 -0
  46. package/templates/package.json +13 -0
  47. package/templates/swarm_runner.js +1594 -0
package/console/index.html ADDED
@@ -0,0 +1,694 @@
1
+ <!DOCTYPE html>
2
+ <html lang="es">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>HIVEN STUDIO — Mente Enjambre & Agente Cognitivo Autónomo</title>
7
+ <link rel="icon" type="image/png" href="assets/hiven_logo_v2.png">
8
+ <link rel="preconnect" href="https://fonts.googleapis.com">
9
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
+ <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700&family=Outfit:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
11
+ <link rel="stylesheet" href="style.css?v=3.2.0">
12
+ <script>
13
+ if (localStorage.getItem('hiven_github_pat') || sessionStorage.getItem('hiven_github_pat')) {
14
+ document.documentElement.classList.add('is-authenticated-pre');
15
+ }
16
+ </script>
17
+ </head>
18
+ <body>
19
+
20
+ <!-- RESTRICTIVE AUTH GATE / LOCKSCREEN -->
21
+ <div id="auth-gate" class="auth-gate-screen">
22
+ <div class="auth-gate-card">
23
+ <div class="gate-header">
24
+ <img src="assets/hiven_logo_v2.png" alt="Hiven Logo" class="gate-logo">
25
+ <h2>HIVEN STUDIO</h2>
26
+ <div class="gate-tag">Autonomous Swarm Intelligence Engine</div>
27
+ <p class="gate-desc">Introduce tu GitHub Personal Access Token (PAT) para acceder a la consola. Se almacena localmente y permite despachar Kōmbees a coste $0.</p>
28
+ </div>
29
+
30
+ <form id="form-auth-gate" onsubmit="handleAuthGateSubmit(event)">
31
+ <div class="form-group" style="width: 100%; text-align: left;">
32
+ <label for="gatePatInput">GitHub Personal Access Token (PAT)</label>
33
+ <input type="password" id="gatePatInput" class="form-control" placeholder="ghp_xxxxxxxxxxxxxxxxxxxx" required>
34
+ <small class="form-text">Requiere permisos de <code>repo</code> y <code>workflow</code>.</small>
35
+ </div>
36
+
37
+ <button type="submit" class="btn btn-primary mt-3" style="width: 100%; justify-content: center;" id="btnGateSubmit">
38
+ <span>🐝 Conectar y Acceder a Hiven</span>
39
+ </button>
40
+ </form>
41
+ </div>
42
+ </div>
43
+
44
+ <!-- MAIN APPLICATION LAYOUT -->
45
+ <div id="app-layout" class="app-layout-wrapper">
46
+ <!-- Header / Navigation Bar -->
47
+ <header class="topbar">
48
+ <div class="brand">
49
+ <img src="assets/hiven_logo_v2.png" alt="Hiven Logo" class="brand-logo">
50
+ <div class="brand-info">
51
+ <div class="brand-title">HIVEN <span class="version-badge">v3.2.0</span></div>
52
+ <div class="brand-subtitle">Autonomous Swarm Intelligence & Honeycombs Memory</div>
53
+ </div>
54
+ </div>
55
+
56
+ <div class="topbar-actions">
57
+ <div class="swarm-indicator" id="swarmIndicator">
58
+ <span class="pulse-dot"></span>
59
+ <span class="status-text">Swarm Engine Listo</span>
60
+ </div>
61
+
62
+ <div class="user-profile-badge" id="userProfileBadge">
63
+ <img id="userAvatar" src="assets/hiven_logo_v2.png" alt="User Avatar" class="user-avatar-mini">
64
+ <span id="userLoginName" class="user-login-text">Conectado</span>
65
+ <button class="btn-logout" onclick="handleLogout()" title="Cerrar Sesión">Desconectar</button>
66
+ </div>
67
+
68
+ <a href="https://github.com/amglogicalis/hiven-repo-public" target="_blank" class="btn btn-icon" title="Ver Repositorio en GitHub">
69
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z"/></svg>
70
+ </a>
71
+ </div>
72
+ </header>
73
+
74
+ <!-- Main Container -->
75
+ <div class="layout">
76
+ <!-- Sidebar Navigation -->
77
+ <aside class="sidebar">
78
+ <nav class="nav-menu">
79
+ <button class="nav-item active" onclick="switchTab('tab-dashboard')">
80
+ <span class="nav-icon">🐝</span> Dashboard & Enjambre
81
+ </button>
82
+ <button class="nav-item" onclick="switchTab('tab-dispatcher')">
83
+ <span class="nav-icon">🚀</span> Despachar Misión
84
+ </button>
85
+ <button class="nav-item" onclick="switchTab('tab-history')">
86
+ <span class="nav-icon">📋</span> Inventario de Misiones
87
+ </button>
88
+ <button class="nav-item" onclick="switchTab('tab-honeycombs')">
89
+ <span class="nav-icon">🍯</span> Hiven Honeycombs
90
+ </button>
91
+ <button class="nav-item" onclick="switchTab('tab-issuebot')">
92
+ <span class="nav-icon">🤖</span> Issue Bot Gateway
93
+ </button>
94
+ <button class="nav-item" onclick="switchTab('tab-docs')">
95
+ <span class="nav-icon">📖</span> Guía & Documentación
96
+ </button>
97
+ </nav>
98
+
99
+ <div class="sidebar-footer">
100
+ <div class="terra-badge">
101
+ <span>🌱 Terra Ecosystem</span>
102
+ <small>Zero-Cost Swarm</small>
103
+ </div>
104
+ </div>
105
+ </aside>
106
+
107
+ <!-- Content Workspace -->
108
+ <main class="content">
109
+
110
+ <!-- TAB 1: DASHBOARD -->
111
+ <section id="tab-dashboard" class="tab-pane active">
112
+ <div class="section-header">
113
+ <div>
114
+ <h2>Dashboard & Visualizador de Fases del Enjambre</h2>
115
+ <p class="text-muted">Monitoreo en tiempo real del pipeline de 4 fases y ciclo de auto-sanación (Self-Healing).</p>
116
+ </div>
117
+ <button class="btn btn-primary btn-sm" onclick="switchTab('tab-dispatcher')">
118
+ <span>+ Nueva Misión</span>
119
+ </button>
120
+ </div>
121
+
122
+ <!-- Quick Stats -->
123
+ <div class="stats-grid">
124
+ <div class="stat-card">
125
+ <div class="stat-icon">🐝</div>
126
+ <div class="stat-value" id="statActiveWorkers">0</div>
127
+ <div class="stat-label">Kōmbees Activos</div>
128
+ </div>
129
+ <div class="stat-card">
130
+ <div class="stat-icon">🍯</div>
131
+ <div class="stat-value" id="statPatternsCount">14</div>
132
+ <div class="stat-label">Celdas Honeycombs</div>
133
+ </div>
134
+ <div class="stat-card">
135
+ <div class="stat-icon">🩹</div>
136
+ <div class="stat-value" id="statSelfHealingRate">99.2%</div>
137
+ <div class="stat-label">Tasa de Éxito con Self-Healing</div>
138
+ </div>
139
+ <div class="stat-card">
140
+ <div class="stat-icon">🚀</div>
141
+ <div class="stat-value" id="statTotalPRs">0</div>
142
+ <div class="stat-label">Pull Requests Generadas</div>
143
+ </div>
144
+ </div>
145
+
146
+ <!-- Live Swarm Pipeline Stepper -->
147
+ <div class="card mt-4">
148
+ <div class="card-header">
149
+ <h3>Pipeline Multi-Fase del Enjambre</h3>
150
+ <span class="badge badge-amber" id="currentPhaseBadge">Fase: Standby</span>
151
+ </div>
152
+
153
+ <div class="pipeline-stepper">
154
+ <div class="step-node active" id="step0">
155
+ <div class="step-circle">0</div>
156
+ <div class="step-title">Deterministic Extractor</div>
157
+ <div class="step-desc">AST & Dependencies</div>
158
+ </div>
159
+ <div class="step-connector"></div>
160
+ <div class="step-node" id="step1">
161
+ <div class="step-circle">1</div>
162
+ <div class="step-title">Swarm Architect</div>
163
+ <div class="step-desc">Task Graph (DAG)</div>
164
+ </div>
165
+ <div class="step-connector"></div>
166
+ <div class="step-node" id="step2">
167
+ <div class="step-circle">2</div>
168
+ <div class="step-title">Parallel Coders</div>
169
+ <div class="step-desc">Surgical Diffs</div>
170
+ </div>
171
+ <div class="step-connector"></div>
172
+ <div class="step-node" id="step3">
173
+ <div class="step-circle">3</div>
174
+ <div class="step-title">Shadow Sandbox</div>
175
+ <div class="step-desc">Test & Verify</div>
176
+ </div>
177
+ <div class="step-connector"></div>
178
+ <div class="step-node" id="stepHeal">
179
+ <div class="step-circle">🩹</div>
180
+ <div class="step-title">Self-Healing Loop</div>
181
+ <div class="step-desc">Auto-Fix Error Traces</div>
182
+ </div>
183
+ <div class="step-connector"></div>
184
+ <div class="step-node" id="step4">
185
+ <div class="step-circle">4</div>
186
+ <div class="step-title">Pull Request</div>
187
+ <div class="step-desc">Publish & Patch</div>
188
+ </div>
189
+ </div>
190
+
191
+ <!-- Activity Terminal -->
192
+ <div class="terminal-box mt-3" id="dashboardTerminal">
193
+ <div class="terminal-line"><span class="term-time">[HIVEN-SYS]</span> Mente enjambre lista. Esperando instrucciones de misión...</div>
194
+ <div class="terminal-line"><span class="term-time">[HONEYCOMBS]</span> Celdas de memoria cargadas desde Honeycombs Engine ($0 Cost).</div>
195
+ </div>
196
+ </div>
197
+ </section>
198
+
199
+ <!-- TAB 2: DISPATCHER -->
200
+ <section id="tab-dispatcher" class="tab-pane">
201
+ <div class="section-header">
202
+ <div>
203
+ <h2>Despachador de Misiones Autónomas</h2>
204
+ <p class="text-muted">Configura y lanza un enjambre multi-agente con personalización total.</p>
205
+ </div>
206
+ </div>
207
+
208
+ <div class="card">
209
+ <form id="dispatchForm" onsubmit="handleDispatchSwarm(event)">
210
+ <div class="form-grid">
211
+ <div class="form-group full-width">
212
+ <label for="inputRepo">Repositorio Objetivo <span class="required">*</span></label>
213
+ <input type="text" id="inputRepo" class="form-control" placeholder="usuario/mi-repositorio" required>
214
+ <small class="form-text">Debe tener permisos de escritura con tu GitHub PAT.</small>
215
+ </div>
216
+
217
+ <div class="form-group full-width">
218
+ <label for="inputPrompt">Instrucción / Misión en Lenguaje Natural <span class="required">*</span></label>
219
+ <textarea id="inputPrompt" class="form-control" rows="4" placeholder="Ej: Implementar autenticación JWT con endpoints de login/register, agregar tests unitarios y documentar en el README..." required></textarea>
220
+ </div>
221
+
222
+ <div class="form-group">
223
+ <label for="inputBranch">Rama de Trabajo <span class="text-muted">(opcional)</span></label>
224
+ <input type="text" id="inputBranch" class="form-control" placeholder="hiven/feature-auth">
225
+ <small class="form-text">Si se omite, se creará una rama automática con timestamp.</small>
226
+ </div>
227
+
228
+ <div class="form-group">
229
+ <label for="inputBaseBranch">Rama Base <span class="text-muted">(opcional)</span></label>
230
+ <input type="text" id="inputBaseBranch" class="form-control" placeholder="main" value="main">
231
+ </div>
232
+
233
+ <div class="form-group">
234
+ <label for="inputWorkers">Kōmbees Concurrentes <span class="text-muted">(opcional)</span></label>
235
+ <div class="range-with-val">
236
+ <input type="range" id="inputWorkers" min="1" max="10" value="4" oninput="document.getElementById('workersVal').innerText = this.value">
237
+ <span id="workersVal" class="range-val">4</span>
238
+ </div>
239
+ <small class="form-text">Sub-swarms paralelos para particionar archivos.</small>
240
+ </div>
241
+
242
+ <div class="form-group">
243
+ <label for="inputTestCmd">Comando de Verificación / Tests <span class="text-muted">(opcional)</span></label>
244
+ <input type="text" id="inputTestCmd" class="form-control" placeholder="npm test || pytest">
245
+ <small class="form-text">Comando ejecutado en el Shadow Sandbox para validar cambios.</small>
246
+ </div>
247
+
248
+ <div class="form-group">
249
+ <label for="inputRetries">Reintentos de Auto-Sanación (Self-Healing) <span class="text-muted">(opcional)</span></label>
250
+ <select id="inputRetries" class="form-control">
251
+ <option value="1">1 Reintento</option>
252
+ <option value="3" selected>3 Reintentos (Recomendado)</option>
253
+ <option value="5">5 Reintentos (Máxima Robustez)</option>
254
+ </select>
255
+ </div>
256
+
257
+ <div class="form-group">
258
+ <label for="inputDryRun">Modo de Ejecución <span class="text-muted">(opcional)</span></label>
259
+ <select id="inputDryRun" class="form-control">
260
+ <option value="false" selected>⚡ Despacho Real (GitHub Actions PR)</option>
261
+ <option value="true">🧪 Simulación Local (Dry-Run)</option>
262
+ </select>
263
+ </div>
264
+ </div>
265
+
266
+ <div class="form-actions mt-4">
267
+ <button type="submit" class="btn btn-primary" id="btnDispatch">
268
+ <span>🐝 Lanzar Enjambre Autónomo</span>
269
+ </button>
270
+ <button type="button" class="btn btn-secondary" onclick="generateWorkflowOnly()">
271
+ <span>📄 Generar Workflow YAML</span>
272
+ </button>
273
+ </div>
274
+ </form>
275
+ </div>
276
+ </section>
277
+
278
+ <!-- TAB 3: INVENTORY -->
279
+ <section id="tab-history" class="tab-pane">
280
+ <div class="section-header">
281
+ <div>
282
+ <h2>Inventario de Misiones & Pull Requests</h2>
283
+ <p class="text-muted">Registro histórico de tareas resueltas y Pull Requests gestionadas por Hiven.</p>
284
+ </div>
285
+ <button class="btn btn-secondary btn-sm" onclick="loadSwarmsHistory()">
286
+ <span>🔄 Refrescar</span>
287
+ </button>
288
+ </div>
289
+
290
+ <div class="card">
291
+ <div class="table-responsive">
292
+ <table class="data-table">
293
+ <thead>
294
+ <tr>
295
+ <th>Swarm ID</th>
296
+ <th>Repositorio</th>
297
+ <th>Estado</th>
298
+ <th>Misión</th>
299
+ <th>Auto-Sanación</th>
300
+ <th>Fecha</th>
301
+ <th>Pull Request</th>
302
+ </tr>
303
+ </thead>
304
+ <tbody id="swarmsTableBody">
305
+ <tr>
306
+ <td colspan="7" class="text-center text-muted">No hay misiones recientes. Despacha una en la pestaña "Despachar Misión".</td>
307
+ </tr>
308
+ </tbody>
309
+ </table>
310
+ </div>
311
+ </div>
312
+ </section>
313
+
314
+ <!-- TAB 4: HONEYCOMBS MEMORY (DUAL-LEVEL) -->
315
+ <section id="tab-honeycombs" class="tab-pane">
316
+ <div class="section-header">
317
+ <div>
318
+ <h2>Hiven Honeycombs (Memoria K/V de Dos Niveles)</h2>
319
+ <p class="text-muted">Gestión de memoria local aislada y sincronización con la Mente Colmena Global de Terra.</p>
320
+ </div>
321
+ <div class="actions-group">
322
+ <button class="btn btn-secondary btn-sm" onclick="exportHoneycombs()">
323
+ <span>💾 Exportar JSON</span>
324
+ </button>
325
+ <button class="btn btn-danger btn-sm" onclick="clearHoneycombs()">
326
+ <span>🗑️ Purgar Memoria Local</span>
327
+ </button>
328
+ </div>
329
+ </div>
330
+
331
+ <!-- LEVEL 2: GLOBAL HIVEMIND CONTROL CARD -->
332
+ <div class="card hivemind-banner mb-4">
333
+ <div class="hivemind-header">
334
+ <div class="hivemind-info">
335
+ <div class="hivemind-title">
336
+ <span class="hivemind-icon">🌐</span>
337
+ <h3>Mente Colmena Global (Red Colectiva Terra)</h3>
338
+ </div>
339
+ <p class="hivemind-desc">
340
+ Comparte automáticamente tus patrones y directivas de código validadas con los demás enjambres de Terra y aliméntate de los patrones globales para alcanzar un <strong>99% de efectividad</strong>.
341
+ </p>
342
+ </div>
343
+ <div class="hivemind-toggle-wrapper">
344
+ <label class="toggle-switch">
345
+ <input type="checkbox" id="checkGlobalHivemind" onchange="handleHivemindCheckboxClick(event)">
346
+ <span class="slider"></span>
347
+ </label>
348
+ <span id="badgeHivemindStatus" class="status-pill text-muted">Aislado / Solo Local</span>
349
+ </div>
350
+ </div>
351
+ <div class="hivemind-footer mt-3">
352
+ <small class="text-muted">Patrones Globales Sincronizados: <strong id="statGlobalPatternsCount" style="color:var(--accent-hiven)">0</strong> | Estado: <span id="textHivemindSyncStatus">Desconectado</span></small>
353
+ </div>
354
+ </div>
355
+
356
+ <!-- LEVEL 1: LOCAL HONEYCOMBS -->
357
+ <div class="section-sub-header mb-3">
358
+ <h3>🏠 Nivel 1: Celdas & Patrones Locales (Tu Enjambre)</h3>
359
+ <p class="text-muted">Memoria privada de tu sesión y repositorio. Puedes purgar celdas completas o eliminar patrones específicos.</p>
360
+ </div>
361
+
362
+ <div class="honeycomb-grid" id="honeycombsGrid">
363
+ <!-- Populated dynamically with individual delete buttons -->
364
+ </div>
365
+
366
+ <!-- LEVEL 2 DISPLAY: GLOBAL PATTERNS (IF ACTIVE) -->
367
+ <div id="globalHivemindSection" style="display: none;" class="mt-4">
368
+ <div class="section-sub-header mb-3">
369
+ <h3>🌐 Nivel 2: Patrones Federados de la Mente Colmena</h3>
370
+ <p class="text-muted">Conocimiento colectivo recibido de la red global de Terra.</p>
371
+ </div>
372
+ <div class="honeycomb-grid" id="globalHoneycombsGrid">
373
+ <!-- Populated dynamically when global hivemind is active -->
374
+ </div>
375
+ </div>
376
+ </section>
377
+
378
+ <!-- TAB 5: ISSUE BOT GATEWAY -->
379
+ <section id="tab-issuebot" class="tab-pane">
380
+ <div class="section-header">
381
+ <div>
382
+ <h2>Issue Bot Gateway (Vercel Bridge)</h2>
383
+ <p class="text-muted">Configura y verifica la escucha de menciones <code>@hiven</code> en Issues de GitHub.</p>
384
+ </div>
385
+ </div>
386
+
387
+ <div class="card">
388
+ <div class="bridge-status-box">
389
+ <div class="bridge-badge">🤖 GitHub App Gateway</div>
390
+ <h3>Listener de Webhooks para Issues</h3>
391
+ <p>Permite que cualquier desarrollador invoque a Hiven en un Issue o Pull Request simplemente escribiendo un comentario con <code>@hiven</code> o <code>/hiven</code>.</p>
392
+
393
+ <div class="webhook-endpoint-box mt-3">
394
+ <label>Endpoint Webhook en Producción (Recibe HTTP POST de GitHub):</label>
395
+ <div class="copy-field">
396
+ <code>https://hiven-komb-queen.vercel.app/webhooks/github</code>
397
+ <button class="btn btn-sm btn-secondary" onclick="navigator.clipboard.writeText('https://hiven-komb-queen.vercel.app/webhooks/github'); showToast('Endpoint copiado');">Copiar</button>
398
+ </div>
399
+ </div>
400
+
401
+ <div class="mt-4">
402
+ <h4>Estado de Activación:</h4>
403
+ <div class="status-indicator-box">
404
+ <span class="status-pill active">✓ Gateway Operativo</span>
405
+ <span class="status-pill active">✓ Honeycombs K/V Nativo Activo ($0)</span>
406
+ <span class="status-pill active">✓ Zero-Cost Marginal Mode</span>
407
+ </div>
408
+ </div>
409
+ </div>
410
+ </div>
411
+ </section>
412
+
413
+ <!-- TAB 6: DOCS & FAQ -->
414
+ <section id="tab-docs" class="tab-pane">
415
+ <div class="section-header">
416
+ <div>
417
+ <h2>Guía Oficial de Arquitectura, Prompting & Documentación Técnica</h2>
418
+ <p class="text-muted">Manual exhaustivo de funcionamiento, mejores prácticas, ingeniería de prompts y referencia de parámetros.</p>
419
+ </div>
420
+ </div>
421
+
422
+ <div class="docs-container">
423
+ <div class="docs-sidebar">
424
+ <a href="#doc-overview" class="docs-link active">1. Visión General</a>
425
+ <a href="#doc-phases" class="docs-link">2. Pipeline de 4 Fases</a>
426
+ <a href="#doc-selfhealing" class="docs-link">3. Bucle de Auto-Sanación</a>
427
+ <a href="#doc-params" class="docs-link">4. Referencia de Parámetros</a>
428
+ <a href="#doc-prompting" class="docs-link">5. Manual de Buen Prompting</a>
429
+ <a href="#doc-honeycombs" class="docs-link">6. Memoria Honeycombs (2 Niveles)</a>
430
+ <a href="#doc-api" class="docs-link">7. Consumo Externo & Sphexn</a>
431
+ <a href="#doc-faq" class="docs-link">8. Preguntas Frecuentes (FAQ)</a>
432
+ </div>
433
+
434
+ <div class="docs-content">
435
+ <!-- SECTION 1 -->
436
+ <article id="doc-overview">
437
+ <h3>1. Visión General & Filosofía Soberana</h3>
438
+ <p><strong>Hiven V3</strong> es el motor de ingeniería de software autónomo multi-agente de coste \$0 del ecosistema Terra. Su propósito es resolver prácticamente cualquier tarea de desarrollo (desde utilidades aisladas hasta refactorizaciones complejas de sistemas concurrentes) con una tasa de efectividad real cercana al <strong>99%</strong>.</p>
439
+ <div class="callout-box">
440
+ <strong>Principio Fundamental:</strong> Hiven no es un chatbot que adivina código a ciegas; es un enjambre determinista que descompone tareas en grafos acíclicos (Task DAG), aplica parches quirúrgicos mínimos, valida su propio código en sandboxes efímeros y se auto-corrige ante cualquier error antes de publicar una Pull Request.
441
+ </div>
442
+ </article>
443
+
444
+ <!-- SECTION 2 -->
445
+ <article id="doc-phases" class="mt-4">
446
+ <h3>2. Pipeline de 4 Fases</h3>
447
+ <p>Cada misión despachada atraviesa cinco estados estrictos y trazables:</p>
448
+ <ul>
449
+ <li><strong>Fase 0 (Deterministic Extractor):</strong> Inspecciona la topología del repositorio, paquetes instalados, archivos de configuración (<code>package.json</code>, <code>tsconfig.json</code>, etc.) y árboles sintácticos (AST) sin depender de alucinaciones del modelo.</li>
450
+ <li><strong>Fase 1 (Swarm Architect):</strong> Analiza la misión y consulta la memoria Honeycombs para extraer directivas previas. Divide la instrucción en un Grafo de Tareas (Task DAG) con dependencias ordenadas.</li>
451
+ <li><strong>Fase 2 (Parallel Coders):</strong> Nodos Kōmbee concurrentes escriben código exclusivamente mediante <strong>bloques quirúrgicos <code>SEARCH/REPLACE</code></strong>. Esto garantiza que nunca se borren imports preexistentes, comentarios ni lógica no relacionada.</li>
452
+ <li><strong>Fase 3 (Shadow Sandbox):</strong> Ejecuta de forma aislada las suites de verificación y tests unitarios. Si todos los tests pasan en verde (<code>exit 0</code>), avanza a la Fase 4.</li>
453
+ <li><strong>Fase 4 (Consolidator):</strong> Consolida los parches, genera el commit atómico, sube la rama remota y abre la Pull Request oficial en GitHub con un resumen estructurado de cambios.</li>
454
+ </ul>
455
+ </article>
456
+
457
+ <!-- SECTION 3 -->
458
+ <article id="doc-selfhealing" class="mt-4">
459
+ <h3>3. Bucle de Auto-Sanación (Self-Healing Loop)</h3>
460
+ <p>El pilar principal que eleva la efectividad de Hiven al 99% es su bucle de auto-recuperación:</p>
461
+ <p>Si la Fase 3 detecta un fallo de compilación, sintaxis o error en los tests (<code>exit code !== 0</code>), Hiven <strong>no da por perdida la misión ni emite una PR rota</strong>. En su lugar:</p>
462
+ <ol>
463
+ <li>Captura el <code>stderr</code>, el stack trace y las aserciones fallidas de la prueba.</li>
464
+ <li>Sintetiza la causa raíz del fallo y la almacena temporalmente como un <code>dontDirective</code> en Honeycombs para no repetir la misma equivocación.</li>
465
+ <li>Reinyecta el contexto de error a un sub-enjambre de corrección quirúrgica.</li>
466
+ <li>Genera un parche de reparación y repite la prueba en el Sandbox (hasta el número de reintentos configurado).</li>
467
+ <li>Una vez que la suite concluye con éxito, guarda el aprendizaje ganador como <code>doDirective</code>.</li>
468
+ </ol>
469
+ </article>
470
+
471
+ <!-- SECTION 4 -->
472
+ <article id="doc-params" class="mt-4">
473
+ <h3>4. Referencia de Parámetros del Despachador</h3>
474
+ <p>A continuación se detallan todos los controles configurables para lanzar misiones con máxima precisión:</p>
475
+
476
+ <table class="param-table">
477
+ <thead>
478
+ <tr>
479
+ <th>Parámetro</th>
480
+ <th>Tipo / Rango</th>
481
+ <th>Por Defecto</th>
482
+ <th>Descripción & Mejores Prácticas</th>
483
+ </tr>
484
+ </thead>
485
+ <tbody>
486
+ <tr>
487
+ <td><code>Repositorio Objetivo</code></td>
488
+ <td>String (<code>owner/repo</code>)</td>
489
+ <td><em>Requerido</em></td>
490
+ <td>Repositorio de GitHub donde se ejecutarán los cambios. Tu GitHub PAT debe tener permisos de lectura/escritura (<code>repo</code> y <code>workflow</code>).</td>
491
+ </tr>
492
+ <tr>
493
+ <td><code>Instrucción / Misión</code></td>
494
+ <td>Textarea (Natural Language)</td>
495
+ <td><em>Requerido</em></td>
496
+ <td>Especificación detallada de la tarea a resolver. Debe incluir contexto del archivo objetivo, entradas, salidas y restricciones técnicas.</td>
497
+ </tr>
498
+ <tr>
499
+ <td><code>Rama de Trabajo</code></td>
500
+ <td>String</td>
501
+ <td><code>hiven/patch-[id]</code></td>
502
+ <td>Rama en la que el enjambre publicará los commits. Si se deja en blanco, Hiven genera automáticamente un identificador único con timestamp.</td>
503
+ </tr>
504
+ <tr>
505
+ <td><code>Rama Base</code></td>
506
+ <td>String</td>
507
+ <td><code>main</code></td>
508
+ <td>Rama de destino contra la cual se abrirá la Pull Request (habitualmente <code>main</code>, <code>master</code> o <code>develop</code>).</td>
509
+ </tr>
510
+ <tr>
511
+ <td><code>Kōmbees Concurrentes</code></td>
512
+ <td>Integer (1 a 10)</td>
513
+ <td><code>4</code></td>
514
+ <td>Nodos trabajadores en paralelo. Usa <strong>2</strong> para módulos pequeños o utilidades simples; <strong>4</strong> para features estándar; y <strong>6 a 10</strong> para refactors multi-archivo masivos.</td>
515
+ </tr>
516
+ <tr>
517
+ <td><code>Comando de Test</code></td>
518
+ <td>String (Shell Command)</td>
519
+ <td><em>Opcional</em></td>
520
+ <td>Comando que el Shadow Sandbox ejecutará para validar los cambios (ej. <code>npm test</code>, <code>pytest</code>, o una línea en Node <code>node -e "..."</code>). <strong>Es la brújula que guía al Self-Healing</strong>.</td>
521
+ </tr>
522
+ <tr>
523
+ <td><code>Reintentos Self-Healing</code></td>
524
+ <td>Select (1, 3, 5)</td>
525
+ <td><code>3 Reintentos</code></td>
526
+ <td>Número máximo de rondas de auto-corrección si los tests fallan. Se recomienda mantenerlo en <strong>3</strong> para garantizar el 99% de éxito sin sobrecostes.</td>
527
+ </tr>
528
+ <tr>
529
+ <td><code>Modo de Ejecución</code></td>
530
+ <td>Select (Real / Dry-Run)</td>
531
+ <td><code>Despacho Real</code></td>
532
+ <td><strong>Despacho Real:</strong> Crea ramas y Pull Request real en GitHub.<br><strong>Simulación Local:</strong> Ejecuta el Task Graph y valida diffs quirúrgicos sin modificar GitHub.</td>
533
+ </tr>
534
+ </tbody>
535
+ </table>
536
+ </article>
537
+
538
+ <!-- SECTION 5 -->
539
+ <article id="doc-prompting" class="mt-4">
540
+ <h3>5. Manual de Buen Prompting para Enjambres Autónomos</h3>
541
+ <p>La calidad y velocidad de resolución de Hiven dependen directamente de cómo estructures la instrucción. <strong>Los agentes autónomos prosperan cuando les das criterios de éxito verificables, no intenciones difusas.</strong></p>
542
+
543
+ <h4>La Fórmula en 4 Pasos de un Prompt de Alto Rendimiento:</h4>
544
+ <ol>
545
+ <li><strong>Ubicación & Módulo Objetivo:</strong> Especifica el archivo o directorio a crear/modificar (ej. <code>src/utils/math.ts</code>).</li>
546
+ <li><strong>Contrato de la Interfaz:</strong> Define nombres de funciones, tipos de datos esperados, parámetros y valores de retorno.</li>
547
+ <li><strong>Casos Límite & Restricciones:</strong> Manejo de errores (qué excepciones lanzar, timeouts, validación de nulos o strings vacíos).</li>
548
+ <li><strong>Criterio de Validación:</strong> Indica qué suite de tests debe acompañar al código.</li>
549
+ </ol>
550
+
551
+ <div class="prompt-comparison">
552
+ <div class="prompt-box bad">
553
+ <div class="prompt-header">❌ Mal Prompt (Vago & Ambiguo)</div>
554
+ <p>Crea un validador de emails y ponle pruebas.</p>
555
+ <p class="text-muted" style="font-size:0.76rem;">Problema: No especifica archivo, estándar de regex, si debe lanzar excepción o retornar booleano, ni qué casos edge probar.</p>
556
+ </div>
557
+
558
+ <div class="prompt-box good">
559
+ <div class="prompt-header">✅ Buen Prompt (Específico & Determinista)</div>
560
+ <code>Crear en src/validators/email.js la función isWorkEmail(email).
561
+ - Debe validar formato RFC 5322 y rechazar dominios gratuitos (gmail, yahoo, hotmail).
562
+ - Retornar { valid: boolean, domain: string, reason?: string }.
563
+ - Si el input no es string, lanzar TypeError.
564
+ - Exportar en ESM y crear suite de tests con al menos 6 casos límite.</code>
565
+ </div>
566
+ </div>
567
+
568
+ <div class="prompt-comparison mt-3">
569
+ <div class="prompt-box bad">
570
+ <div class="prompt-header">❌ Mal Prompt (Refactorización)</div>
571
+ <p>Optimiza la base de datos y que vaya más rápida.</p>
572
+ <p class="text-muted" style="font-size:0.76rem;">Problema: No define qué consultas optimizar ni qué métricas o índices añadir.</p>
573
+ </div>
574
+
575
+ <div class="prompt-box good">
576
+ <div class="prompt-header">✅ Buen Prompt (Refactorización Quirúrgica)</div>
577
+ <code>En src/db/repository.ts, refactorizar getUserSessions(userId):
578
+ - Sustituir la concatenación de queries por un pool con prepared statements.
579
+ - Implementar caché LRU en memoria con TTL de 60 segundos.
580
+ - Mantener exactamente la misma firma y tipo de retorno UserSession[].
581
+ - Ejecutar npm run test:db en el Sandbox.</code>
582
+ </div>
583
+ </div>
584
+ </article>
585
+
586
+ <!-- SECTION 6 -->
587
+ <article id="doc-honeycombs" class="mt-4">
588
+ <h3>6. Hiven Honeycombs: Memoria de Dos Niveles</h3>
589
+ <p>Honeycombs es el sistema de memoria colectiva de Hiven. No almacena fragmentos de código fuente pesados, sino <strong>reglas heurísticas compactas</strong> indexadas por lenguaje (<code>hive_patterns:{ext}</code>):</p>
590
+ <ul>
591
+ <li><strong><code>doDirective</code>:</strong> Buenas prácticas y patrones de diseño que superaron las pruebas unitarias.</li>
592
+ <li><strong><code>dontDirective</code>:</strong> Antipatrones y trampas que provocaron errores en el sandbox, aprendidos durante el bucle de auto-sanación.</li>
593
+ </ul>
594
+
595
+ <h4>Los Dos Niveles de Operación:</h4>
596
+ <ul>
597
+ <li><strong>Nivel 1 (Memoria Local Privada):</strong> Se almacena en tu propia caché y en el repositorio privado <code>.hiven-storage</code>. Te permite inspeccionar cada patrón y purgar de forma granular aquellos que ya no te interesen con el botón <code>🗑️</code>.</li>
598
+ <li><strong>Nivel 2 (Mente Colmena Global):</strong> Conexión federada con la red colectiva de Terra. Al activarla mediante el interruptor superior (tras aceptar el modal de confirmación y privacidad), tu enjambre comparte sus directivas aprendidas y se nutre del conocimiento de otros desarrolladores sin exponer jamás credenciales, tokens ni código sensible.</li>
599
+ </ul>
600
+ </article>
601
+
602
+ <!-- SECTION 7 -->
603
+ <article id="doc-api" class="mt-4">
604
+ <h3>7. Consumo Externo (SDK TypeScript & Swarm REST API para Sphexn)</h3>
605
+ <p>Hiven está diseñado para ser consumido como un servicio autónomo tanto por desarrolladores humanos como por otros agentes inteligentes del ecosistema Terra (como <strong>Sphexn</strong>):</p>
606
+
607
+ <h4>Opción A: SDK Programático (<code>terra-hiven</code>)</h4>
608
+ <div class="terminal-box">
609
+ <div class="terminal-line"><span class="term-time">npm</span> i terra-hiven</div>
610
+ </div>
611
+ <p class="mt-2">En tu código TypeScript o JavaScript:</p>
612
+ <div class="terminal-box">
613
+ <div class="terminal-line">import { Hiven } from "terra-hiven";</div>
614
+ <div class="terminal-line">const hiven = new Hiven();</div>
615
+ <div class="terminal-line">const res = await hiven.dispatchSwarm({ repo: "org/repo", instruction: "..." });</div>
616
+ </div>
617
+
618
+ <h4 class="mt-3">Opción B: Swarm REST API (HTTP JSON)</h4>
619
+ <p>Al iniciar el servidor local con <code>hiven console</code> o <code>hiven serve</code>, se habilita la API REST oficial en <code>http://localhost:7460</code>:</p>
620
+ <ul>
621
+ <li><code>POST /api/v1/swarm/dispatch</code>: Despacha un enjambre recibiendo el JSON de configuración.</li>
622
+ <li><code>GET /api/v1/swarm/:id</code>: Consulta el estado en tiempo real, rondas de auto-sanación y URL de la PR.</li>
623
+ <li><code>GET /api/v1/honeycombs/patterns?lang=ts</code>: Devuelve los Do's & Don'ts aprendidos para TypeScript.</li>
624
+ <li><code>GET /api/v1/health</code>: Comprobación de estado operativo del motor.</li>
625
+ </ul>
626
+ </article>
627
+
628
+ <!-- SECTION 8 -->
629
+ <article id="doc-faq" class="mt-4">
630
+ <h3>8. Preguntas Frecuentes & Consejos de Producción (FAQ)</h3>
631
+ <details class="faq-item">
632
+ <summary><strong>¿Hiven tiene algún coste de infraestructura mensual?</strong></summary>
633
+ <p>No. Funciona bajo el modelo de coste marginal $0 de Terra. Utiliza los minutos gratuitos de GitHub Actions, almacenamiento soberano en repositorios Git y GitHub Pages.</p>
634
+ </details>
635
+ <details class="faq-item">
636
+ <summary><strong>¿Por qué las ejecuciones directas tardan apenas unos segundos?</strong></summary>
637
+ <p>Porque la extracción de dependencias y los diffs quirúrgicos se computan en memoria RAM ($O(1)$) y el Shadow Sandbox valida el código en procesos locales efímeros sin la sobrecarga de arranque de máquinas virtuales en la nube.</p>
638
+ </details>
639
+ <details class="faq-item">
640
+ <summary><strong>¿Qué permisos necesita mi GitHub PAT?</strong></summary>
641
+ <p>Requiere exclusivamente los scopes de <code>repo</code> (para crear ramas, commits y Pull Requests) y <code>workflow</code> (para despachar GitHub Actions si usas el modo nube).</p>
642
+ </details>
643
+ <details class="faq-item">
644
+ <summary><strong>¿Cómo garantizo que Hiven no borre código existente?</strong></summary>
645
+ <p>Hiven utiliza bloques de búsqueda y reemplazo contextuales con diffs quirúrgicos (`applySearchReplace`). Nunca reescribe un archivo completo de cero a menos que sea un archivo de nueva creación.</p>
646
+ </details>
647
+ </article>
648
+ </div>
649
+ </div>
650
+ </section>
651
+
652
+ </main>
653
+ </div>
654
+ </div>
655
+
656
+ <!-- HIVEMIND CONFIRMATION MODAL -->
657
+ <div id="hivemindModal" class="modal">
658
+ <div class="modal-content" style="max-width: 520px;">
659
+ <div class="modal-header">
660
+ <div style="display:flex; align-items:center; gap:10px;">
661
+ <span style="font-size:1.6rem;">🐝🌐</span>
662
+ <h3 style="color:var(--accent-hiven); font-size:1.2rem;">¿Unirte a la Mente Colmena Global?</h3>
663
+ </div>
664
+ <button class="modal-close" onclick="cancelHivemindActivation()">&times;</button>
665
+ </div>
666
+ <div class="modal-body" style="text-align:left; font-size:0.88rem; line-height:1.55; color:var(--text-main);">
667
+ <p style="margin-bottom:12px;">
668
+ Al activar la <strong>Mente Colmena Global</strong>, tu enjambre compartirá los patrones técnicos aprendidos (Do's & Don'ts) con la red colectiva de Terra y tú también te alimentarás de la memoria global acumulada.
669
+ </p>
670
+ <div style="background:rgba(215,237,4,0.08); border:1px solid var(--border-color); border-radius:8px; padding:14px; margin-bottom:14px;">
671
+ <div style="font-weight:700; color:var(--accent-hiven); margin-bottom:6px;">⚠️ Privacidad & Transparencia:</div>
672
+ <p style="font-size:0.82rem; color:var(--text-muted);">
673
+ Esto mejora drásticamente el rendimiento y el aprendizaje al 99%, pero los patrones descubiertos en tus misiones se federarán públicamente en la colmena. Ningún dato sensible (tokens, credenciales o código fuente íntegro) es compartido jamás.
674
+ </p>
675
+ </div>
676
+ <p style="font-size:0.85rem; color:var(--text-muted);">
677
+ ¿Deseas activar la Mente Colmena Global de Hiven ahora?
678
+ </p>
679
+ </div>
680
+ <div class="modal-footer mt-4" style="display:flex; justify-content:flex-end; gap:10px;">
681
+ <button class="btn btn-secondary" onclick="cancelHivemindActivation()">Cancelar</button>
682
+ <button class="btn btn-primary" onclick="confirmHivemindActivation()">
683
+ <span>✓ Sí, Activar Mente Colmena</span>
684
+ </button>
685
+ </div>
686
+ </div>
687
+ </div>
688
+
689
+ <!-- Toast Notification -->
690
+ <div id="toast" class="toast"></div>
691
+
692
+ <script src="app.js?v=3.2.0"></script>
693
+ </body>
694
+ </html>