roninforge-hono

Plugin para Cursor de Hono v4 (framework web edge TypeScript) + TypeScript. Fijado en hono ^4.12.19, @hono/zod-validator ^0.8.0, @hono/zod-openapi ^1.4.0 (peer zod ^4.x), @hono/node-server ^2.0.3 (Node 20+). Enseña las APIs v4 que los LLMs entrenados con datos anteriores a 2024 no conocen (c.json() siempre tipado, el validador lanza HTTPException, getCookie/setCookie de hono/cookie, c.env como propiedad, streamText de hono/streaming, showRoutes de hono/dev, getRuntimeKey de hono/adapter, fire(app) de hono/service-worker, enlace de Static Assets de Workers en lugar del obsoleto serveStatic, JSR @hono/hono para Deno). Detecta más de 50 regresiones de LLM con pares MAL / CORRECTO en TypeScript.

No existe Hono v5. La última estable es v4.12.19. Cualquier "v5" en código generado es alucinación.

El problema

Los propios mantenedores de Hono presentaron el Issue #3906 ("archivo llm.txt") y el Issue #4812 ("Habilidad oficial de AI Agent para Hono") explícitamente porque "los LLMs básicamente no tienen conocimiento de cómo funciona el Hono más reciente." Los datos de entrenamiento anteriores a 2025 son de la era v3. Los LLMs emiten:

APIs eliminadas v3 -> v4

• c.jsonT() en lugar de c.json() (siempre tipado desde v4.0.0)
• c.stream() / c.streamText() como métodos de Contexto (movidos a hono/streaming en v4)
• c.env() forma de función (ahora propiedad; detección de tiempo de ejecución mediante getRuntimeKey() de hono/adapter)
• c.req.cookie() (eliminado; use getCookie(c) de hono/cookie)
• app.showRoutes(), app.routerName (movidos a hono/dev)
• addEventListener('fetch') + app.handleEvent() (sintaxis de Service Worker; use export default { fetch: app.fetch })
• Rutas app.head(...) (HEAD derivado automáticamente de GET en v4)
• Importación hono/nextjs (use hono/vercel)
• Importación global hono/middleware (use subruta por middleware)
• Métodos de acceso c.req.headers() / c.req.body() / c.req.signal() (use c.req.raw.*)
• FC con hijos implícitos (use PropsWithChildren<P>)
• app.fire() (obsoleto en v4.8.0; use fire(app) de hono/service-worker)
• import { Hono } from 'https://deno.land/x/hono/mod.ts' en Deno (obsoleto desde v4.4.0; use jsr:@hono/hono)

Filtraciones de Express / Koa / Fastify (la clase más grande)

• Falta return en c.json() (resuelve a undefined; v4 lanza "Context is not finalized")
• res.json() / res.send() en lugar de c.json() (no hay res en Hono)
• Firma de middleware (req, res, next) (use (c, next))
• Middleware de error (err, req, res, next) (use app.onError + HTTPException)
• app.use(express.json()) analizador de cuerpo (Hono analiza bajo demanda mediante c.req.json())
• import cors from 'cors' desde npm (use hono/cors)
• supertest para pruebas (use app.request() / testClient(app))
• c.req.body como ya analizado (es un ReadableStream)
• c.req.parseBody() para JSON (solo formulario / multipart)
• c.req.text() luego c.req.json() (cuerpo consumido dos veces)
• Asignación en línea c.userId = ... (use c.set('userId', ...) con Variables tipadas)

Errores de inferencia TypeScript / RPC

• new Hono() sin genéricos Bindings / Variables (c.env es {})
• Rutas definidas como sentencias (app.get(...) luego app.post(...)) - pierde tipos RPC
• Llamadas a sub-app app.route() como sentencias - misma regla
• Controladores estilo Rails pasando Context (pierde inferencia de parámetros de ruta, según Mejores Prácticas de Hono)
• app.use('/path', zValidator(...)) en lugar de como argumento de ruta (error TS: 'json' no asignable a 'never')
• c.notFound() en rutas consumidas por RPC (no se puede tipar en el cliente)
• new Response(JSON.stringify(...)) en rutas RPC (el cliente ve unknown)
• URL relativa hc<AppType>('/') (lanza error en $url())
• Importación por valor de la app del servidor en el bundle del cliente (arrastra drizzle-orm, fs, dependencias nativas - el peligro #1 de hinchazón del bundle RPC)
• Middleware sin createMiddleware<Env> (los tipos de Variables no se propagan)

Errores de Cloudflare Workers

• process.env.X en código de Workers (undefined; use c.env.X con Bindings tipados)
• Importaciones fs / path en Workers (no hay sistema de archivos)
• Indicador legacy compatibility_flags: ["node_compat"] (use nodejs_compat)
• serveStatic obsoleto de hono/cloudflare-workers (desde v4.3.0; use enlace de assets)
• Falta c.executionCtx.waitUntil() para operaciones fire-and-forget
• Comprobación de verdad if (c.executionCtx) (getter lanza error en Bun y Next.js App Router)
• D1 .run() / .first() / .all() sin await (inserción cancelada cuando el worker termina)
• Actualización WebSocket sin reenvío de Durable Object (el estado desaparece)

Brechas de seguridad / producción

• Sin middleware secureHeaders()
• Sin csrf() en mutaciones autenticadas con cookies
• cors({ origin: '*', credentials: true }) (los navegadores lo ignoran silenciosamente; AJAX falla)
• Falta bodyLimit() en rutas POST / PUT y fijar hono >= 4.9.7 por CVE-2025-59139
• Cookies sin httpOnly / secure / sameSite / path
• sameSite: 'None' sin secure: true (ignorado silenciosamente)
• Middleware de registro de cuerpo sin redacción (fuga de contraseñas / tokens / PII)
• Sin etag() / cache() en GETs estáticos
• Clave JWT escrita en el código (se filtra a través del bundle)
• Construir JSON grande en memoria en lugar de streamText (límite de 128MB en Workers)

Errores de enrutamiento / estructurales

• Manejador notFound de sub-app (código muerto; solo se activa el de nivel superior)
• Inconsistencia de barra final (/users vs /users/ son rutas diferentes por defecto)
• await next() más de una vez (duplica el trabajo aguas abajo)
• Superposición app.use(prefix, mw) + app.route(prefix, subApp) (el middleware se ejecuta dos veces)
• app.basePath('/api') como sentencia (el prefijo se pierde del tipo)

Tiempo de ejecución incorrecto silenciosamente

• serve(app) en @hono/node-server (use serve({ fetch: app.fetch }))
• export default app en Workers (use export default { fetch: app.fetch })
• Bun.serve({ fetch: app }) (use app.fetch)

Problemas reales más pequeños

• c.req.query() sin argumento cuando se espera un solo valor
• c.req.param('id') en middleware global (indefinido donde :id no está en la ruta)
• OpenAPI hecho a mano sin @hono/zod-openapi
• cors() montado DESPUÉS de las rutas (nunca coincide)

Por qué este plugin (frente a las reglas comunitarias existentes de Hono)

Un puñado de reglas de Hono ya existen en cursor.directory y en awesome-cursorrules (PR #152): cubren los retornos de c.json(), zValidator + Zod, c.env para Workers, rutas encadenadas para RPC y exportación app.fetch de Workers. Tienen tres problemas estructurales que este plugin soluciona: