roninforge-hono

Plugin per Cursor per Hono v4 (framework web TypeScript edge) + TypeScript. Bloccato su 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+). Insegna le API v4 che gli LLM addestrati su dati pre-2024 non conoscono (c.json() sempre tipizzato, il validatore lancia HTTPException, getCookie/setCookie da hono/cookie, c.env come proprietà, streamText da hono/streaming, showRoutes da hono/dev, getRuntimeKey da hono/adapter, fire(app) da hono/service-worker, associazione Static Assets di Workers invece della deprecata serveStatic, JSR @hono/hono per Deno). Individua oltre 50 regressioni degli LLM con coppie ERRATO / CORRETTO in TypeScript.

Non esiste Hono v5. L'ultima stabile è v4.12.19. Qualsiasi "v5" nel codice generato è un'allucinazione.

Il problema

Gli stessi manutentori di Hono hanno aperto Issue #3906 ("file llm.txt") e Issue #4812 ("Abilità ufficiale AI Agent per Hono") proprio perché "gli LLM non hanno praticamente conoscenza di come funziona l'ultimo Hono." I dati di addestramento pre-2025 sono dell'era v3. Gli LLM emettono:

API rimosse da v3 a v4

• c.jsonT() invece di c.json() (sempre tipizzato dalla v4.0.0)
• c.stream() / c.streamText() come metodi di Context (spostati in hono/streaming nella v4)
• c.env() forma funzionale (ora proprietà; rilevamento runtime tramite getRuntimeKey() da hono/adapter)
• c.req.cookie() (rimosso; usa getCookie(c) da hono/cookie)
• app.showRoutes(), app.routerName (spostati in hono/dev)

Perdite da Express / Koa / Fastify (la classe più grande)

• return mancante su c.json() (risolve a undefined; v4 lancia "Context is not finalized")
• res.json() / res.send() invece di c.json() (non esiste res in Hono)
• Firma middleware (req, res, next) (usa (c, next))
• Middleware errori (err, req, res, next) (usa app.onError + HTTPException)
• app.use(express.json()) parser body (Hono analizza su richiesta tramite c.req.json())

Errori di inferenza TypeScript / RPC

• new Hono() senza generici Bindings / Variables (c.env è {})
• Route definite come istruzioni (app.get(...) poi app.post(...)) - perde tipi RPC
• Chiamate app.route() per sotto-app come istruzioni - stessa regola
• Controller stile Rails che passano Context (perde inferenza dei parametri di percorso, secondo le Best Practices di Hono)
• app.use('/path', zValidator(...)) invece che come argomento di route (errore TS: 'json' non assegnabile a 'never')
• c.notFound() in route consumate da RPC (non può essere tipizzato sul client)

Insidie di Cloudflare Workers

• process.env.X nel codice Workers (undefined; usa c.env.X con Bindings tipizzate)
• Import fs / path nei Workers (nessun filesystem)
• Flag legacy compatibility_flags: ["node_compat"] (usa nodejs_compat)
• serveStatic deprecato da hono/cloudflare-workers (dalla v4.3.0; usa asset binding)
• c.executionCtx.waitUntil() mancante per fire-and-forget
• Controllo truthy if (c.executionCtx) (getter lancia su Bun e Next.js App Router)
• D1 .run() / / non await (insert annullato quando il worker termina)

Lacune di sicurezza / produzione

• Nessun middleware secureHeaders()
• Nessun csrf() su mutazioni autenticate da cookie
• cors({ origin: '*', credentials: true }) (i browser lo scartano silenziosamente; AJAX fallisce)
• bodyLimit() mancante su route POST / PUT e blocca hono >= 4.9.7 per CVE-2025-59139
• Cookie senza httpOnly / secure / sameSite / path
• sameSite: 'None' senza secure: true (scartato silenziosamente)
• Middleware di logging del body senza redazione (perdita di password / token / PII)
• Nessun etag() / su GET statici

Bug di routing / strutturali

• Gestore notFound di sotto-app (codice morto; solo il livello principale si attiva)
• Incoerenza slash finale (/users vs /users/ sono route diverse per default)
• await next() più di una volta (raddoppia il lavoro a valle)
• app.use(prefix, mw) + app.route(prefix, subApp) sovrapposizione (il middleware si attiva due volte)
• app.basePath('/api') come istruzione (il prefisso viene scartato dal tipo)

Runtime silenziosamente errato

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

Problemi reali minori

• c.req.query() senza argomento quando si aspetta un singolo valore
• c.req.param('id') in middleware globale (undefined dove :id non è nel percorso)
• OpenAPI scritto a mano senza @hono/zod-openapi
• cors() montato DOPO le route (non corrisponde mai)

Perché questo plugin (rispetto alle regole Hono della community esistenti)

Alcune regole Hono esistono già su cursor.directory e in awesome-cursorrules (PR #152): coprono c.json() returns, zValidator + Zod, c.env per Workers, route concatenate per RPC, e app.fetch Workers export. Hanno tre problemi strutturali che questo plugin risolve:

1. Non coprono le API rimosse da v3 a v4. Gli LLM continuano ad emettere c.jsonT, c.stream, c.env(), c.req.cookie, app.showRoutes, il barrel hono/middleware, e app.handleEvent - tutti rimossi nella v4.0.0 (febbraio 2024). Le regole esistenti li permettono silenziosamente.
2. Omettono la classe di perdita Express. (req, res, next), (err, req, res, next), npm cors, app.use(express.json()), supertest, return mancante su c.json - tutto accade costantemente nel codice Hono generato dagli LLM. Le regole esistenti li trattano come casi isolati.

Questo plugin include:

• 10 regole MDC con globs appropriati in modo che i controlli su route / RPC si attivino su src/routes/**, quelli Workers su wrangler.{toml,jsonc} + entry Workers, quelli di sicurezza su file middleware, ecc.
• 59 anti-pattern documentati con coppie ERRATO / CORRETTO in TypeScript
• 5 skill: /hono-new-route, /hono-rpc-setup, /hono-cloudflare-workers-setup, /hono-migrate-to-v4, /hono-validate
• 1 agente revisore con raggruppamento per gravità (CRITICO / ERRORE / AVVISO / NIT) e controlli per file
• 2 progetti fixture: correct-sample (gold standard Hono 4.12.19 + Workers + D1 + Drizzle + Zod) e anti-pattern-sample (retaggio Hono v3 con oltre 25 violazioni tracciate)

Installazione

Copia le regole, le skill e l'agente nella configurazione Cursor del tuo progetto. Prima esegui un backup dei file esistenti; cp -r sovrascriverà le regole con lo stesso nome.

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

# Usa -n per evitare di sovrascrivere una regola personalizzata esistente con lo stesso nome.
cp -rn roninforge-hono/rules/*  your-project/.cursor/rules/
cp -rn roninforge-hono/skills/* your-project/.cursor/skills/
cp -rn roninforge-hono/agents/* your-project/.cursor/agents/

Oppure vendi l'intero repository come sottomodulo git sotto your-project/.cursor/plugins/. Consulta la documentazione dei plugin Cursor per il percorso di installazione globale corrente sulla tua versione di Cursor.

Cosa è incluso

Regole (10 file)

Skill (5 comandi)

Agente (1 subagente)

Fixture

tests/fixtures/correct-sample/ è un progetto Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod snello che dimostra la forma gold standard: route concatenate, RPC tipizzato, zValidator come argomento route, risposte tipizzate c.json({ ... } as const, status), stack secureHeaders + cors + csrf + bodyLimit, app.onError + app.notFound a livello principale, export default { fetch: app.fetch } satisfies ExportedHandler<Env>.

tests/fixtures/anti-pattern-sample/ è l'inverso. Ogni file viola un anti-pattern numerato. package.json blocca hono ^3.12.0 + cors ^2.8.5 + supertest ^6.3.0 + @hono/sentry ^1.0.0 + lucia ^3.2.0 apposta - l'era v3 è la base dei dati di addestramento LLM per la maggior parte dei modelli pre-2025, oltre a companion deprecati che gli LLM raccomandano ancora. Le violazioni tracciate includono: return mancante su c.json (#1), forma handler Express (req, res) (#2), middleware (req, res, next) (#3), (err, req, res, next) (#4), npm cors (#6), supertest (#12), c.jsonT (#13), addEventListener('fetch') + app.handleEvent (#15), (#16), chiamata funzionale (#17), barrel (#20), (#23), nessun Bindings/Variables (#24), in route RPC (#29), in Workers (#34), flag (#36), da (#37), D1 non await (#40), cors + credentials (#43), cookie senza (#45), senza (#46), segreto JWT hard-coded (#48), sotto-app (#50), come istruzione (#53), su Workers (#55), riferimenti deprecati + .

Versionamento

Le regole targettano hono ^4.12.19 con Node 20+ (quando su Node), Bun latest, Deno latest, Wrangler ^4.0.0. La maggior parte dei pattern funziona fino a Hono 4.0.0 (febbraio 2024) con le differenze indicate inline. Pin floor:

• hono >= 4.9.7 obbligatorio - fix bypass bodyLimit CVE-2025-59139 / GHSA-92vj-g62v-jqhh
• hono >= 4.12.18 obbligatorio se si utilizza JSX SSR - rafforzamento di nomi tag, nomi attributo, iniezione CSS
• @hono/node-server >= 2.0.0 richiede Node 20+
• @hono/zod-openapi >= 1.0.0 richiede zod ^4.0.0 (il peer è SOLO ^4.0.0, non ^3.x)
• compatibility_date >= "2024-09-23" richiesto affinché nodejs_compat implichi nodejs_compat_v2

Dove la regola cita una versione (c.json() sempre tipizzato dalla v4.0.0, c.text() tipizzato dalla v4.3.0, JSR per Deno dalla v4.4.0, secureHeaders Permissions-Policy dalla v4.6.0, validatore Standard Schema dalla v4.7.0, fire(app) dalla v4.8.0, JSR parseResponse dalla v4.9.0, URL base tipizzato su hc dalla v4.11.0, metodo $path() dalla v4.12.0), verifica rispetto al changelog della versione che hai installato prima di adottare.

Licenza

MIT - vedi LICENSE

Collegamenti

• Documentazione ufficiale Hono
• GitHub Hono
• Guida alla migrazione Hono (v3 -> v4)
• Best Practices Hono
• RPC Hono
• Guida framework Cloudflare Workers per Hono
• Documentazione plugin Cursor
• RoninForge

Altro da RoninForge

RoninForge costruisce strumenti gratuiti per sviluppatori che lavorano con assistenti di codifica AI:

• Confronto prezzi API LLM - prezzi token di Claude, GPT, Gemini, DeepSeek, Mistral e Grok affiancati, verificati rispetto alle pagine ufficiali dei prezzi
• Calcolatore crediti AI GitHub Copilot - stima il tuo consumo mensile di crediti con fatturazione basata sull'uso
• Tutti i plugin Cursor