zugzbot 1.6.0 → 1.7.0

package/.opencode/agents/sdd-tester.md

@@ -68,12 +68,7 @@ Eres el Validador de Contratos (sdd-tester) del flujo SDD. Tu trabajo es ejecuta
 - **Auto-generación de Plantillas (OBLIGATORIO)**: Al comenzar, ejecuta obligatoriamente `sdd_generate_tests` para autogenerar las plantillas a partir de los `test_scenarios` del contrato. Las plantillas ya incluyen imports reales, mocks estándar (Proxy lucide-react, mock reactivo next-themes), y assertions significativas basadas en el `then` de cada escenario. NO las reescribas desde cero.
 - **NO explorar el código**: Tu brief ya contiene los archivos de producción a testear y los patrones de mock pre-armados. NO hagas `read` masivos de componentes, NO hagas `glob` ciegos. Solo lee el archivo de test específico que estés arreglando.
 - **Preparación de Puerto**: Llama proactivamente a `sdd_free_port` para liberar el puerto de pruebas.
-- **Ejecución Incremental/Dirigida**: Ejecuta la suite de pruebas de forma focalizada apuntando únicamente a los archivos de test específicos relacionados con la funcionalidad modificada (ej. `npx vitest run src/__tests__/<test_name>.test.tsx` o `pytest tests/unit/<test_name>.py` en lugar de correr toda la base de pruebas), acelerando exponencialmente los tiempos de espera.
-- **Timeout duro OBLIGATORIO**: SIEMPRE ejecuta vitest con `--testTimeout=10000 --bail=1` para fallar rápido en el primer error. NUNCA ejecutes `vitest` sin estos flags. Esto previene cuelgues infinitos por imports circulares o chains de Providers que happy-dom no puede resolver.
-  ```bash
-  npx vitest run --testTimeout=10000 --bail=1 --reporter=verbose src/__tests__/<file>.test.tsx
-  ```
-  Si el comando excede 60 segundos, ABORTA inmediatamente y reporta el cuelgue. NO esperes más de 1 minuto bajo ninguna circunstancia.
+- **Ejecución Incremental/Dirigida (Uso Mandatorio de Tool de Tests)**: Para ejecutar la suite de pruebas de forma focalizada ahorrando una enorme cantidad de tokens de logs de consola, **DEBES** utilizar la herramienta `sdd_run_tests({ file: "src/__tests__/<test_name>.test.tsx" })` (o la ruta correspondiente en pytest). Solo utiliza comandos `bash` directos (como `npx vitest run --testTimeout=10000 --bail=1 --reporter=verbose ...`) si la herramienta `sdd_run_tests` reporta un fallo de entorno o si necesitas depurar localmente. Si un comando de tests excede 60 segundos, ABORTA de inmediato y reporta el cuelgue.
 - **Si el test runner se cuelga**: Antes de reintentar, ejecuta `npx tsc --noEmit` y `npm run build` para validar la compilación. Si ambos pasan, el problema es del test runner mismo (happy-dom + componente complejo). Reporta al orquestador como "rollback evitable" — el código de producción es válido.
 - **Linter Focalizado**: Ejecuta `npx eslint` apuntando específicamente a los archivos de producción modificados listados en `files_affected` del brief y a tus archivos de test (ej. `npx eslint src/components/blocks/MyBlock.tsx src/__tests__/MyBlock.test.tsx`), optimizando el análisis estático.
 - **Resolución Proactiva de Fallas**: Si los tests fallan debido a problemas menores de mocking, importaciones incorrectas, llaves duplicadas en React o configuraciones de test, **tienes autorización total para editarlos y repararlos tú mismo** dentro de `tests/` o `src/__tests__/`. Solo si el error es un fallo lógico en el código de producción de la aplicación (el cual tienes prohibido modificar), debes reportar un rollback a `F2_IMPLEMENTATION`.

package/.opencode/plugins/sdd-bridge.ts

@@ -436,6 +436,12 @@ export const SddBridgePlugin: Plugin = async ({ project, client, $, directory, w
                 try { fs.rmSync(playwrightTmpDir, { recursive: true, force: true }) } catch (e) {}
               }
 
+              // 2.5 Clear ZCS raw_context cache
+              const rawContextDir = path.resolve(openspecDir, ".raw_context")
+              if (fs.existsSync(rawContextDir)) {
+                try { fs.rmSync(rawContextDir, { recursive: true, force: true }) } catch (e) {}
+              }
+
               // 3. Clear transient metrics file
               const metricsPath = path.resolve(openspecDir, ".sdd_session_metrics.json")
               if (fs.existsSync(metricsPath)) {

package/.opencode/rules/sdd-global.md

@@ -96,3 +96,9 @@ Para evitar que los subagentes se queden sin pasos (step/token exhaustion) o acu
 - **Compilación Atómica:** El Coder **debe** implementar y compilar exitosamente cada archivo de forma individual antes de escribir el siguiente. Está estrictamente prohibido escribir todos los componentes de golpe sin ejecutar validaciones intermedias de TypeScript (`tsc --noEmit`).
 - **Verificación Temprana de Dependencias:** El Coder **debe** comprobar en el primer paso de F2 que dependencias de pruebas críticas como `@testing-library/dom` estén correctamente instaladas en proyectos React 19 para evitar fallos intermitentes de tipado en Vitest.
 - **PROHIBICIÓN ESTRICTA DE `todowrite` en Coder/Tester/Deployer/Spec-Writer:** Estas herramientas **no deben invocar** `todowrite` en ningún momento de su sesión. El seguimiento de fases está centralizado en el Orquestador. Inyectar TODOs en subagentes satura su contexto y agota pasos de LLM innecesariamente. El Orquestador solo debe usar `todowrite` **2 veces máximo por sesión**: una al inicio (lista de fases) y otra al final (marcar todas completadas).
+
+## 10. Compresión y Recuperación de Contexto (ZCS)
+Para maximizar la eficiencia en el uso de la ventana de contexto y ahorrar tokens de API, el arnés implementa Zugzbot Context Shaper (ZCS) con un esquema de recuperación reversible (CCR):
+- **Placeholders de Compresión:** Si detectas bloques de texto en el brief o en los logs de error con la estructura `[CONTEXTO_COMPRIMIDO: hash (Tipo: Categoria, Líneas: N)]`, significa que el contenido original ha sido archivado localmente para no saturar tu contexto.
+- **Recuperación bajo demanda (MANDATORIO):** Si necesitas ver el contenido completo y exacto sin comprimir (por ejemplo, para depurar un stack trace de error largo o leer patrones de mock enteros), debes invocar obligatoriamente la herramienta `sdd_retrieve_raw({ hash: "hash_identificador" })`. No asumas ni inventes código o logs que estén comprimidos; recupéralos de forma dirigida.
+

package/.opencode/tools/sdd_compress.ts

@@ -0,0 +1,242 @@
+import { tool } from "@opencode-ai/plugin"
+import fs from "fs"
+import path from "path"
+import crypto from "crypto"
+
+// Helper to safely resolve root directory
+const getRoot = (context: any) => {
+  if (context?.directory && context.directory !== "/") return context.directory;
+  if (context?.worktree && context.worktree !== "/") return context.worktree;
+  if (context?.cwd && context.cwd !== "/") return context.cwd;
+  return process.cwd();
+};
+
+/**
+ * Comprime código fuente eliminando comentarios, docstrings y líneas vacías.
+ */
+export function compressCode(code: string, commentStyle: "slash" | "hash" = "slash"): string {
+  if (!code) return ""
+  
+  let inString: string | null = null
+  let inComment: "single" | "multi" | null = null
+  let result = ""
+  
+  for (let i = 0; i < code.length; i++) {
+    const char = code[i]
+    const nextChar = code[i + 1] || ""
+    
+    if (inComment === "multi") {
+      if (char === "*" && nextChar === "/") {
+        inComment = null
+        i++ // Skip '/'
+      }
+      continue
+    }
+    
+    if (inComment === "single") {
+      if (char === "\n" || char === "\r") {
+        inComment = null
+        result += char
+      }
+      continue
+    }
+    
+    if (inString) {
+      if (char === inString && code[i - 1] !== "\\") {
+        inString = null
+      }
+      result += char
+      continue
+    }
+    
+    // Check for comments based on style
+    if (commentStyle === "slash") {
+      if (char === "/" && nextChar === "*") {
+        inComment = "multi"
+        i++
+        continue
+      }
+      if (char === "/" && nextChar === "/") {
+        inComment = "single"
+        i++
+        continue
+      }
+    } else if (commentStyle === "hash") {
+      if (char === "#") {
+        inComment = "single"
+        continue
+      }
+    }
+    
+    // Check for string start
+    if (char === "'" || char === '"' || char === "`") {
+      inString = char
+    }
+    
+    result += char
+  }
+  
+  // Clean up empty lines
+  return result
+    .split(/\r?\n/)
+    .filter(line => line.trim().length > 0)
+    .join("\n")
+}
+
+/**
+ * Comprime cadenas JSON grandes recortando arrays a un tamaño máximo.
+ */
+export function compressJson(jsonStr: string, maxItems = 3): string {
+  if (!jsonStr) return ""
+  try {
+    const obj = JSON.parse(jsonStr)
+    
+    const prune = (o: any): any => {
+      if (Array.isArray(o)) {
+        if (o.length > maxItems) {
+          const sliced = o.slice(0, maxItems).map(prune)
+          sliced.push(`... [ZCS: ${o.length - maxItems} elementos omitidos]`)
+          return sliced
+        }
+        return o.map(prune)
+      } else if (o !== null && typeof o === "object") {
+        const res: any = {}
+        for (const k of Object.keys(o)) {
+          res[k] = prune(o[k])
+        }
+        return res
+      }
+      return o
+    }
+    
+    return JSON.stringify(prune(obj), null, 2)
+  } catch (e) {
+    // Si no es JSON válido, devolver el texto original
+    return jsonStr
+  }
+}
+
+/**
+ * Comprime logs de consola de tests unitarios (Vitest/pytest),
+ * preservando los fallos, errores y resúmenes de suites.
+ */
+export function compressTestLogs(logs: string): string {
+  if (!logs) return ""
+  const lines = logs.split(/\r?\n/)
+  const result: string[] = []
+  
+  let recordingError = false
+  let errorLinesCount = 0
+  
+  for (const line of lines) {
+    const upper = line.toUpperCase()
+    
+    // Detectar inicio de fallos o errores
+    const isErrorIndicator = 
+      line.includes("FAIL") || 
+      line.includes("Error:") || 
+      line.includes("AssertionError") || 
+      line.includes("❌") || 
+      upper.includes("EXCEPTION") || 
+      upper.includes("FAILED")
+      
+    if (isErrorIndicator) {
+      recordingError = true
+      errorLinesCount = 0
+      result.push(line)
+      continue
+    }
+    
+    if (recordingError) {
+      // Guardar las primeras 8 líneas del error/stack trace
+      if (errorLinesCount < 8) {
+        result.push(line)
+        errorLinesCount++
+      } else {
+        // Truncar stack traces largos del framework (node_modules/vitest, etc.)
+        if (line.trim() === "" || line.includes("PASS") || line.includes("Test Suites:")) {
+          recordingError = false
+          result.push("   [... ZCS: stack trace del framework omitido para ahorrar tokens ...]")
+          result.push(line)
+        }
+      }
+    } else {
+      // Siempre conservar resúmenes e información de suites exitosas
+      const isSummaryIndicator = 
+        line.includes("PASS") || 
+        line.includes("Summary") || 
+        line.includes("Test Suites:") || 
+        line.includes("Tests:") || 
+        line.includes("Snapshots:") || 
+        line.includes("Time:") || 
+        line.includes("Ran all test suites")
+        
+      if (isSummaryIndicator || line.trim().startsWith("✓")) {
+        result.push(line)
+      }
+    }
+  }
+  
+  // Si no se capturaron líneas o todo pasó muy rápido, retornar resumido
+  if (result.length === 0) {
+    return logs.length > 500 ? `${logs.slice(0, 500)}\n... [ZCS: truncado por longitud]` : logs
+  }
+  
+  return result.join("\n")
+}
+
+/**
+ * Registra el contenido crudo en disco (CCR) y devuelve un placeholder comprimido.
+ */
+export function ccrCompress(content: string, category: string, context: any): string {
+  if (!content) return ""
+  
+  const root = getRoot(context)
+  const rawContextDir = path.resolve(root, ".openspec/.raw_context")
+  
+  if (!fs.existsSync(rawContextDir)) {
+    fs.mkdirSync(rawContextDir, { recursive: true })
+  }
+  
+  // Calcular hash del contenido para evitar duplicados
+  const hash = crypto.createHash("sha256").update(content).digest("hex").slice(0, 12)
+  const destFile = path.join(rawContextDir, `${hash}.txt`)
+  
+  // Escribir solo si no existe ya
+  if (!fs.existsSync(destFile)) {
+    fs.writeFileSync(destFile, content, "utf8")
+  }
+  
+  const lineCount = content.split(/\r?\n/).length
+  return `[CONTEXTO_COMPRIMIDO: ${hash} (Tipo: ${category}, Líneas: ${lineCount}). Si necesitas ver el contenido completo sin compresión para editar o depurar, ejecuta la herramienta sdd_retrieve_raw({ hash: "${hash}" })]`
+}
+
+// Tool: sdd_retrieve_raw
+export const retrieve_raw = tool({
+  description: "Recupera un bloque de contexto original sin comprimir (logs, código, JSON) a partir de su hash identificador.",
+  args: {
+    hash: tool.schema.string().describe("El hash de 12 caracteres del contexto que deseas recuperar (ej. 'a1b2c3d4e5f6').")
+  },
+  async execute(args, context) {
+    try {
+      const root = getRoot(context)
+      const hash = args.hash.trim()
+      const rawPath = path.resolve(root, `.openspec/.raw_context/${hash}.txt`)
+      
+      if (!fs.existsSync(rawPath)) {
+        return JSON.stringify({
+          success: false,
+          message: `No se encontró el contexto original para el hash '${hash}'. El caché podría haber sido purgado.`
+        }, null, 2)
+      }
+      
+      const content = fs.readFileSync(rawPath, "utf8")
+      return content
+    } catch (e: any) {
+      return JSON.stringify({
+        success: false,
+        message: `Error al recuperar contexto crudo: ${e.message || e}`
+      }, null, 2)
+    }
+  }
+})

package/.opencode/tools/sdd_core.ts

@@ -2,6 +2,7 @@ import { tool } from "@opencode-ai/plugin"
 import fs from "fs"
 import path from "path"
 import { execSync } from "child_process"
+import { ccrCompress } from "./sdd_compress.ts"
 
 // Helper to safely resolve root directory (avoiding OpenCode bug where worktree is '/' in non-git repos)
 const getRoot = (context: any) => {
@@ -362,6 +363,15 @@ export const set_phase = tool({
         currentState.loopTargetIterations = 1
         currentState.loopCurrentIteration = 1
       }
+      // Clean up raw_context files (ZCS)
+      try {
+        const rawContextDir = path.resolve(root, ".openspec/.raw_context")
+        if (fs.existsSync(rawContextDir)) {
+          fs.rmSync(rawContextDir, { recursive: true, force: true })
+        }
+      } catch (e) {
+        // ignore
+      }
       // Clean up running servers
       const pidFile = getPidFilePath(root)
       if (fs.existsSync(pidFile)) {
@@ -624,16 +634,17 @@ export const save_active_brief = tool({
         const errors = last("errors", 5)
         const design = last("design", 3)
 
-        if (learnings || errors || design) {
+        let brainMemoryStr = ""
+        if (design) brainMemoryStr += `\n### Design (aplicar en estilo):\n${design}\n`
+        if (learnings) brainMemoryStr += `\n### Learnings (patrones validados):\n${learnings}\n`
+        if (errors) brainMemoryStr += `\n### Errors / Regresiones (evitar repetir):\n${errors}\n`
+
+        if (brainMemoryStr) {
           enrichedBrief += `\n\n## [AUTO-INJECTED] Brain Memory (lecciones de sesiones previas)\n`
-          if (design) {
-            enrichedBrief += `\n### Design (aplicar en estilo):\n${design}\n`
-          }
-          if (learnings) {
-            enrichedBrief += `\n### Learnings (patrones validados):\n${learnings}\n`
-          }
-          if (errors) {
-            enrichedBrief += `\n### Errors / Regresiones (evitar repetir):\n${errors}\n`
+          if (brainMemoryStr.length > 1500) {
+            enrichedBrief += ccrCompress(brainMemoryStr, "Brain Memory", context) + "\n"
+          } else {
+            enrichedBrief += brainMemoryStr
           }
         }
       }
@@ -645,31 +656,35 @@ export const save_active_brief = tool({
     try {
       const isNext = contract?.stack?.core?.some((c: string) => /next\.?js/i.test(c))
       if (isNext) {
+        let mockPatterns = `// Mock dinámico de lucide-react (cualquier icono)\n`
+        mockPatterns += `vi.mock("lucide-react", () => new Proxy({}, {\n`
+        mockPatterns += `  get: (_t, prop) => {\n`
+        mockPatterns += `    const Icon = (props: any) => null;\n`
+        mockPatterns += `    Icon.displayName = String(prop);\n`
+        mockPatterns += `    return Icon;\n`
+        mockPatterns += `  },\n`
+        mockPatterns += `}));\n\n`
+        mockPatterns += `// Mock reactivo de next-themes para ThemeToggle\n`
+        mockPatterns += `let theme = "light";\n`
+        mockPatterns += `vi.mock("next-themes", () => ({\n`
+        mockPatterns += `  useTheme: () => ({\n`
+        mockPatterns += `    get theme() { return theme; },\n`
+        mockPatterns += `    setTheme: (t: string) => { theme = t; },\n`
+        mockPatterns += `    get resolvedTheme() { return theme; },\n`
+        mockPatterns += `  }),\n`
+        mockPatterns += `}));\n\n`
+        mockPatterns += `// Mock de next/navigation\n`
+        mockPatterns += `vi.mock("next/navigation", () => ({\n`
+        mockPatterns += `  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), prefetch: vi.fn() }),\n`
+        mockPatterns += `  usePathname: () => "/",\n`
+        mockPatterns += `}));\n`
+
         enrichedBrief += `\n\n## [AUTO-INJECTED] Mock Patterns (Vitest + Testing Library)\n`
-        enrichedBrief += `\`\`\`typescript\n`
-        enrichedBrief += `// Mock dinámico de lucide-react (cualquier icono)\n`
-        enrichedBrief += `vi.mock("lucide-react", () => new Proxy({}, {\n`
-        enrichedBrief += `  get: (_t, prop) => {\n`
-        enrichedBrief += `    const Icon = (props: any) => null;\n`
-        enrichedBrief += `    Icon.displayName = String(prop);\n`
-        enrichedBrief += `    return Icon;\n`
-        enrichedBrief += `  },\n`
-        enrichedBrief += `}));\n\n`
-        enrichedBrief += `// Mock reactivo de next-themes para ThemeToggle\n`
-        enrichedBrief += `let theme = "light";\n`
-        enrichedBrief += `vi.mock("next-themes", () => ({\n`
-        enrichedBrief += `  useTheme: () => ({\n`
-        enrichedBrief += `    get theme() { return theme; },\n`
-        enrichedBrief += `    setTheme: (t: string) => { theme = t; },\n`
-        enrichedBrief += `    get resolvedTheme() { return theme; },\n`
-        enrichedBrief += `  }),\n`
-        enrichedBrief += `}));\n\n`
-        enrichedBrief += `// Mock de next/navigation\n`
-        enrichedBrief += `vi.mock("next/navigation", () => ({\n`
-        enrichedBrief += `  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), prefetch: vi.fn() }),\n`
-        enrichedBrief += `  usePathname: () => "/",\n`
-        enrichedBrief += `}));\n`
-        enrichedBrief += `\`\`\`\n`
+        if (mockPatterns.length > 1000) {
+          enrichedBrief += ccrCompress(mockPatterns, "Mock Patterns", context) + "\n"
+        } else {
+          enrichedBrief += `\`\`\`typescript\n${mockPatterns}\`\`\`\n`
+        }
       }
     } catch (e) {
       // ignore

package/.opencode/tools/sdd_testing.ts

@@ -2,6 +2,7 @@ import { tool } from "@opencode-ai/plugin"
 import fs from "fs"
 import path from "path"
 import { execSync } from "child_process"
+import { compressTestLogs, ccrCompress } from "./sdd_compress.ts"
 
 // Helper to safely resolve root directory (avoiding OpenCode bug where worktree is '/' in non-git repos)
 const getRoot = (context: any) => {
@@ -669,3 +670,62 @@ export const save_playwright_artifacts = tool({
     }
   }
 })
+
+// Tool: sdd_run_tests
+export const run_tests = tool({
+  description: "Ejecuta las pruebas unitarias y de integración del proyecto (Vitest o pytest), comprimiendo la salida para ahorrar tokens.",
+  args: {
+    file: tool.schema.string().optional().describe("La ruta específica del archivo de test a ejecutar (relativa al root). Si no se pasa, corre todos los tests."),
+    timeout: tool.schema.number().optional().default(10000).describe("Timeout en milisegundos para la ejecución de cada test (solo aplicable a Vitest). Default: 10000.")
+  },
+  async execute(args, context) {
+    const root = getRoot(context)
+    const targetDir = getTargetDir(root)
+    const targetPath = targetDir === "." ? root : path.resolve(root, targetDir)
+
+    // Detectar si es un proyecto Python
+    const isPython = fs.existsSync(path.resolve(targetPath, "requirements.txt")) || fs.existsSync(path.resolve(targetPath, "pyproject.toml"))
+
+    // Obtener ruta del archivo relativa al directorio de destino si aplica
+    let testPathArg = ""
+    if (args.file) {
+      const fullPath = path.resolve(root, args.file)
+      testPathArg = path.relative(targetPath, fullPath)
+    }
+
+    let cmd = ""
+    if (isPython) {
+      cmd = `pytest ${testPathArg || "tests/"}`
+    } else {
+      const testTimeout = args.timeout ?? 10000
+      cmd = `npx vitest run --testTimeout=${testTimeout} --bail=1 --reporter=verbose ${testPathArg}`
+    }
+
+    try {
+      const out = execSync(cmd, {
+        cwd: targetPath,
+        encoding: "utf8",
+        timeout: 120_000, // timeout global del proceso de 2 minutos
+        stdio: "pipe"
+      })
+      
+      const compressed = compressTestLogs(out)
+      
+      return JSON.stringify({
+        status: "SUCCESS",
+        message: "Las pruebas se ejecutaron y pasaron exitosamente.",
+        output: compressed.length > 1500 ? ccrCompress(out, "Test Success Output", context) : compressed
+      }, null, 2)
+    } catch (e: any) {
+      const rawOutput = e.stdout?.toString() || e.stderr?.toString() || e.message || ""
+      const compressed = compressTestLogs(rawOutput)
+      
+      return JSON.stringify({
+        status: "FAIL",
+        message: "La ejecución de pruebas falló. Corrige los errores mostrados abajo.",
+        output: compressed.length > 1500 ? ccrCompress(rawOutput, "Test Failure Output", context) : compressed
+      }, null, 2)
+    }
+  }
+})
+

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "zugzbot",
-  "version": "1.6.0",
+  "version": "1.7.0",
+
   "description": "Fácil instalador del arnés SDD de Zugzbot para proyectos OpenCode",
   "type": "module",
   "bin": {