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)

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

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)

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() / / (insert cancelado quando worker termina)

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

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.

Este plugin fornece:

• 10 regras MDC com globs apropriadas para que as verificações de rotas / RPC disparem em src/routes/**, verificações Workers em wrangler.{toml,jsonc} + entrada Worker, verificações de segurança em arquivos de middleware, etc.
• 59 antipadrões documentados com pares RUIM / CORRETO em TypeScript
• 5 habilidades: /hono-new-route, /hono-rpc-setup, /hono-cloudflare-workers-setup, /hono-migrate-to-v4, /hono-validate
• 1 agente revisor com agrupamento por severidade (CRITICAL / ERROR / WARN / NIT) e verificações por arquivo
• 2 projetos de fixture: correct-sample (padrão ouro Hono 4.12.19 + Workers + D1 + Drizzle + Zod) e anti-pattern-sample (herança Hono v3 com 25+ violações rastreadas)

Instalação

Copie as regras, habilidades e agente para a configuração do Cursor do seu projeto. Faça backup dos arquivos existentes primeiro; cp -r sobrescreverá regras de mesmo nome.

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

# Use -n para evitar sobrescrever uma regra personalizada existente de mesmo nome.
cp -rn roninforge-hono/rules/*  seu-projeto/.cursor/rules/
cp -rn roninforge-hono/skills/* seu-projeto/.cursor/skills/
cp -rn roninforge-hono/agents/* seu-projeto/.cursor/agents/

Ou forneça o repositório inteiro como um submódulo git em seu-projeto/.cursor/plugins/. Consulte a documentação de plugins do Cursor para o caminho atual de instalação global na sua versão do Cursor.

O que está incluído

Regras (10 arquivos)

Habilidades (5 comandos)

Agente (1 subagente)

Fixtures

tests/fixtures/correct-sample/ é um projeto enxuto Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod demonstrando a forma padrão ouro: rotas encadeadas, RPC tipado, zValidator como argumento de rota, c.json({ ... } as const, status) respostas tipadas, pilha secureHeaders + cors + csrf + bodyLimit, app.onError + app.notFound no nível superior, export default { fetch: app.fetch } satisfies ExportedHandler<Env>.

tests/fixtures/anti-pattern-sample/ é o inverso. Cada arquivo viola um antipadrão numerado. package.json fixa hono ^3.12.0 + cors ^2.8.5 + supertest ^6.3.0 + @hono/sentry ^1.0.0 + lucia ^3.2.0 de propósito - a era v3 é a linha de base dos dados de treinamento de LLM para a maioria dos modelos pré-2025, além de dependências obsoletas que LLMs ainda recomendam. Violações rastreadas incluem: falta de return em c.json (#1), forma de handler Express (req, res) (#2), middleware (req, res, next) (#3), (err, req, res, next) (#4), cors npm (#6), supertest (#12), c.jsonT (#13), addEventListener('fetch') + app.handleEvent (#15), (#16), chamada de função (#17), barril (#20), (#23), sem Bindings/Variables (#24), em rota RPC (#29), no Workers (#34), flag (#36), de (#37), D1 não aguardado (#40), cors + credentials (#43), cookie sem (#45), sem (#46), segredo JWT codificado (#48), de sub-app (#50), como declaração (#53), no Workers (#55), referências a + obsoletos.

Versionamento

Regras visam hono ^4.12.19 com Node 20+ (quando no Node), Bun mais recente, Deno mais recente, Wrangler ^4.0.0. A maioria dos padrões funciona desde Hono 4.0.0 (fev/2024) com as diferenças indicadas inline. Pisos de versão:

• hono >= 4.9.7 obrigatório - CVE-2025-59139 / GHSA-92vj-g62v-jqhh correção de bypass de bodyLimit
• hono >= 4.12.18 obrigatório se renderizando JSX SSR - endurecimento de nome de tag, nome de atributo, injeção CSS
• @hono/node-server >= 2.0.0 requer Node 20+
• @hono/zod-openapi >= 1.0.0 requer zod ^4.0.0 (peer é APENAS ^4.0.0, não ^3.x)
• compatibility_date >= "2024-09-23" necessário para nodejs_compat implicar nodejs_compat_v2

Onde a regra cita uma versão (c.json() sempre 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 em hc desde v4.11.0, método $path() desde v4.12.0), verifique no changelog a versão que você tem instalada antes de adotar.

Licença

MIT - veja LICENSE

Links

• Documentação oficial do Hono
• GitHub do Hono
• Guia de Migração do Hono (v3 -> v4)
• Melhores Práticas do Hono
• RPC do Hono
• Guia de framework Cloudflare Workers para Hono
• Documentação de Plugins do Cursor
• RoninForge

Mais da RoninForge

RoninForge constrói ferramentas gratuitas para desenvolvedores que trabalham com assistentes de codificação IA:

• Comparação de preços de API LLM - preços de token de Claude, GPT, Gemini, DeepSeek, Mistral e Grok lado a lado, verificados nas páginas oficiais de preços
• Calculadora de Créditos IA do GitHub Copilot - estime seu consumo mensal de créditos sob faturamento baseado em uso
• Todos os plugins do Cursor