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 )

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())

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)

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() / / sin await (inserción cancelada cuando el worker termina)

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() / en GETs estáticos

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:

1. NO cubren las APIs eliminadas v3 -> v4. Los LLMs continúan emitiendo c.jsonT, c.stream, c.env(), c.req.cookie, app.showRoutes, el barrel hono/middleware y app.handleEvent - todos eliminados en v4.0.0 (febrero 2024). Las reglas existentes los permiten silenciosamente.
2. Omiten la clase de filtración de Express. (req, res, next), (err, req, res, next), cors de npm, app.use(express.json()), supertest, falta de return en c.json - todo ocurre constantemente en código Hono generado por LLM. Las reglas existentes los tratan como casos aislados.

Este plugin incluye:

• 10 reglas MDC con globs apropiados para que las comprobaciones de rutas / RPC se activen en src/routes/**, las comprobaciones de Workers en wrangler.{toml,jsonc} + entrada de Worker, las comprobaciones de seguridad en archivos de middleware, etc.
• 59 antipatrones documentados con pares MAL / CORRECTO en TypeScript
• 5 habilidades: /hono-new-route, /hono-rpc-setup, /hono-cloudflare-workers-setup, /hono-migrate-to-v4, /hono-validate
• 1 agente revisor con agrupación por severidad (CRÍTICO / ERROR / ADVERTENCIA / NIT) y comprobaciones por archivo
• 2 proyectos de ejemplo: correct-sample (estándar de oro Hono 4.12.19 + Workers + D1 + Drizzle + Zod) y anti-pattern-sample (resaca de Hono v3 con más de 25 violaciones rastreadas)

Instalación

Copia las reglas, habilidades y agente en la configuración de Cursor de tu proyecto. Haz una copia de seguridad de tus archivos existentes primero; cp -r sobrescribirá las reglas con el mismo nombre.

git clone https://github.com/RoninForge/roninforge-hono.git

# Usa -n para evitar sobrescribir una regla personalizada existente con el mismo nombre.
cp -rn roninforge-hono/rules/*  tu-proyecto/.cursor/rules/
cp -rn roninforge-hono/skills/* tu-proyecto/.cursor/skills/
cp -rn roninforge-hono/agents/* tu-proyecto/.cursor/agents/

O incluye todo el repositorio como un submódulo de git en tu-proyecto/.cursor/plugins/. Consulta la documentación de plugins de Cursor para la ruta de instalación global actual en tu versión de Cursor.

Qué está incluido

Reglas (10 archivos)

Habilidades (5 comandos)

Agente (1 subagente)

Ejemplos

tests/fixtures/correct-sample/ es un proyecto slim Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod que demuestra la forma estándar de oro: rutas encadenadas, RPC tipado, zValidator como argumento de ruta, c.json({ ... } as const, status) respuestas tipadas, pila secureHeaders + cors + csrf + bodyLimit, app.onError + app.notFound a nivel superior, export default { fetch: app.fetch } satisfies ExportedHandler<Env>.

tests/fixtures/anti-pattern-sample/ es el inverso. Cada archivo viola un antipatrón numerado. package.json fija hono ^3.12.0 + cors ^2.8.5 + supertest ^6.3.0 + @hono/sentry ^1.0.0 + lucia ^3.2.0 a propósito - la era v3 es la línea base de datos de entrenamiento de LLM para la mayoría de modelos anteriores a 2025, además de acompañantes obsoletos que los LLM aún recomiendan. Las violaciones rastreadas incluyen: falta return en c.json (#1), forma de manejador Express (req, res) (#2), middleware (req, res, next) (#3), (err, req, res, next) (#4), cors de npm (#6), supertest (#12), c.jsonT (#13), addEventListener('fetch') + app.handleEvent (#15), (#16), llamada de función (#17), barrel (#20), (#23), sin Bindings/Variables (#24), en ruta RPC (#29), en Workers (#34), indicador (#36), de (#37), D1 sin await (#40), cors + credenciales (#43), cookie sin (#45), sin (#46), clave JWT escrita en el código (#48), de sub-app (#50), como sentencia (#53), en Workers (#55), referencias a + obsoletos.

Versiones

Las reglas apuntan a hono ^4.12.19 con Node 20+ (cuando se está en Node), Bun latest, Deno latest, Wrangler ^4.0.0. La mayoría de los patrones funcionan desde Hono 4.0.0 (febrero 2024) con los deltas indicados en línea. Pines mínimos:

• hono >= 4.9.7 obligatorio - corrección de CVE-2025-59139 / GHSA-92vj-g62v-jqhh omisión de bodyLimit
• hono >= 4.12.18 obligatorio si se renderiza JSX SSR - endurecimiento de nombres de etiquetas, nombres de atributos, inyección CSS
• @hono/node-server >= 2.0.0 requiere Node 20+
• @hono/zod-openapi >= 1.0.0 requiere zod ^4.0.0 (peer es SOLO ^4.0.0, no ^3.x)
• compatibility_date >= "2024-09-23" requerido para que nodejs_compat implique nodejs_compat_v2

Donde la regla cita una versión (c.json() siempre tipado desde v4.0.0, c.text() tipado desde v4.3.0, JSR para Deno desde v4.4.0, secureHeaders Permissions-Policy desde v4.6.0, validador Standard Schema desde v4.7.0, fire(app) desde v4.8.0, JSR parseResponse desde v4.9.0, URL base tipada en hc desde v4.11.0, método $path() desde v4.12.0), verifica con el registro de cambios la versión que tienes instalada antes de adoptar.

Licencia

MIT - ver LICENSE

Enlaces

• Documentación oficial de Hono
• GitHub de Hono
• Guía de Migración de Hono (v3 -> v4)
• Mejores Prácticas de Hono
• RPC de Hono
• Guía de framework de Cloudflare Workers para Hono
• Documentación de Plugins de Cursor
• RoninForge

Más de RoninForge

RoninForge construye herramientas gratuitas para desarrolladores que trabajan con asistentes de codificación de IA:

• Comparativa de precios de APIs LLM - Precios de tokens de Claude, GPT, Gemini, DeepSeek, Mistral y Grok lado a lado, verificados con las páginas oficiales de precios
• Calculadora de créditos AI de GitHub Copilot - Estima tu consumo mensual de créditos bajo facturación basada en uso
• Todos los plugins de Cursor