roninforge-hono

Plugin para o Cursor do Hono v4 (framework web TypeScript edge) + TypeScript. Fixado em 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+). Ensina as APIs v4 que LLMs treinados em dados anteriores a 2024 não conhecem (c.json() sempre tipado, validador lança HTTPException, getCookie/setCookie de hono/cookie, c.env como propriedade, streamText de hono/streaming, showRoutes de hono/dev, getRuntimeKey de hono/adapter, fire(app) de hono/service-worker, binding de Static Assets do Workers em vez do obsoleto serveStatic, JSR @hono/hono para Deno). Captura 50+ regressões de LLM com pares RUIM / CORRETO em TypeScript.

Não existe Hono v5. A estável mais recente é v4.12.19. Qualquer "v5" no código gerado é alucinação.

O Problema

Os próprios mantenedores do Hono abriram a Issue #3906 ("llm.txt file") e a Issue #4812 ("Official AI Agent Skill for Hono") explicitamente porque "LLMs praticamente não têm conhecimento de como o Hono mais recente funciona." Dados de treinamento anteriores a 2025 são da era v3. LLMs emitem:

APIs removidas v3 -> v4

• c.jsonT() em vez de c.json() (sempre tipado desde v4.0.0)
• c.stream() / c.streamText() como métodos de Context (movido para hono/streaming no v4)
• c.env() forma de função (agora propriedade; detecção de runtime via getRuntimeKey() de hono/adapter)
• c.req.cookie() (removido; use getCookie(c) de hono/cookie)
• app.showRoutes(), app.routerName (movido para hono/dev)
• addEventListener('fetch') + app.handleEvent() (sintaxe Service Worker; use export default { fetch: app.fetch })
• Rotas app.head(...) (HEAD derivado automaticamente de GET no v4)
• Import hono/nextjs (use hono/vercel)
• Import de barril hono/middleware (use subcaminho por middleware)
• Métodos acessores c.req.headers() / c.req.body() / c.req.signal() (use c.req.raw.*)
• FC com children implícito (use PropsWithChildren<P>)
• app.fire() (obsoleto desde v4.8.0; use fire(app) de hono/service-worker)
• import { Hono } from 'https://deno.land/x/hono/mod.ts' no Deno (desatualizado desde v4.4.0; use jsr:@hono/hono)

Vazamento de Express / Koa / Fastify (a maior classe)

• return ausente em c.json() (resolve para undefined; v4 lança "Context is not finalized")
• res.json() / res.send() em vez de c.json() (não existe res no Hono)
• Assinatura de middleware (req, res, next) (use (c, next))
• Middleware de erro (err, req, res, next) (use app.onError + HTTPException)
• app.use(express.json()) parser de body (Hono faz parsing sob demanda via c.req.json())
• import cors from 'cors' do npm (use hono/cors)
• supertest para testes (use app.request() / testClient(app))
• c.req.body como já parseado (é um ReadableStream)
• c.req.parseBody() para JSON (apenas formulário / multipart)
• c.req.text() seguido de c.req.json() (body consumido duas vezes)
• Atribuição inline c.userId = ... (use c.set('userId', ...) com Variables tipadas)

Erros de inferência TypeScript / RPC

• new Hono() sem genéricos Bindings / Variables (c.env é {})
• Rotas definidas como declarações (app.get(...) depois app.post(...)) - perde tipos RPC
• Chamadas de sub-app app.route() como declarações - mesma regra
• Controladores estilo Rails passando Context por aí (perde inferência de parâmetros de caminho, conforme Best Practices do Hono)
• app.use('/path', zValidator(...)) em vez de como argumento de rota (Erro TS: 'json' not assignable to 'never')
• c.notFound() em rotas consumidas por RPC (não pode tipar no cliente)
• new Response(JSON.stringify(...)) em rotas RPC (cliente vê unknown)
• URL relativa hc<AppType>('/') (lança erro em $url())
• Import de valor do app servidor no bundle do cliente (arrasta drizzle-orm, fs, dependências nativas - a armadilha #1 de inchaço de bundle RPC)
• Middleware sem createMiddleware<Env> (tipos de Variables não propagam)

Pegadinhas do Cloudflare Workers

• process.env.X em código Workers (undefined; use c.env.X com Bindings tipado)
• Imports fs / path no Workers (não há sistema de arquivos)
• Flag legado compatibility_flags: ["node_compat"] (use nodejs_compat)
• serveStatic obsoleto de hono/cloudflare-workers (desde v4.3.0; use asset binding)
• c.executionCtx.waitUntil() ausente para fire-and-forget
• Verificação de verdade if (c.executionCtx) (getter lança erro no Bun e no Next.js App Router)
• Chamadas D1 não aguardadas .run() / .first() / .all() (insert cancelado quando worker termina)
• Atualização WebSocket sem encaminhamento Durable Object (estado desaparece)

Lacunas de segurança / produção

• Sem middleware secureHeaders()
• Sem csrf() em mutações autenticadas por cookie
• cors({ origin: '*', credentials: true }) (navegadores silenciosamente descartam; AJAX falha)
• bodyLimit() ausente em rotas POST / PUT e fixar hono >= 4.9.7 para CVE-2025-59139
• Cookies sem httpOnly / secure / sameSite / path
• sameSite: 'None' sem secure: true (silenciosamente descartado)
• Middleware de registro de body sem redação (vazamento de senhas / tokens / PII)
• Sem etag() / cache() em GETs estáticos
• Segredo JWT codificado (vaza pelo bundle)
• Construir JSON grande em memória em vez de streamText (limite de 128MB do Workers)

Bugs de roteamento / estrutura

• Handler notFound de sub-app (código morto; apenas o nível superior dispara)
• Inconsistência de barra final (/users vs /users/ são rotas diferentes por padrão)
• await next() mais de uma vez (duplica trabalho a jusante)
• app.use(prefix, mw) + app.route(prefix, subApp) sobreposição (middleware dispara duas vezes)
• app.basePath('/api') como declaração (prefixo é descartado do tipo)

Runtime silenciosamente errado

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

Problemas reais menores

• c.req.query() sem argumento quando espera valor único
• c.req.param('id') em middleware global (undefined onde :id não está no caminho)
• OpenAPI feito à mão sem @hono/zod-openapi
• cors() montado APÓS as rotas (nunca corresponde)

Por que este plugin (em vez das regras existentes da comunidade Hono)

Algumas regras Hono já existem em cursor.directory e em awesome-cursorrules (PR #152): cobrem retornos de c.json(), zValidator + Zod, c.env para Workers, rotas encadeadas para RPC e export Workers app.fetch. Elas têm três problemas estruturais que este plugin resolve:

1. Elas NÃO cobrem as APIs removidas v3 -> v4. LLMs continuam emitindo c.jsonT, c.stream, c.env(), c.req.cookie, app.showRoutes, o barril hono/middleware e app.handleEvent - todos removidos no v4.0.0 (fev/2024). Regras existentes permitem silenciosamente.
2. Elas omitem a classe de vazamento Express. (req, res, next), (err, req, res, next), cors do npm, app.use(express.json()), supertest, falta de return em c.json - tudo acontece constantemente em código Hono gerado por LLM. Regras existentes tratam como casos isolados.
3. Elas perdem padrões de segurança e a fixação do CVE. Nenhuma impõe secureHeaders() / csrf(); nenhuma menciona bodyLimit CVE-2025-59139 (correção no v4.9.7); nenhuma aborda as armadilhas do cliente RPC (URL relativa, vazamento de import de valor, tipagem c.notFound).