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)
• addEventListener('fetch') + app.handleEvent() (sintassi Service Worker; usa export default { fetch: app.fetch })
• app.head(...) (HEAD derivato automaticamente da GET nella v4)
• hono/nextjs import (usa hono/vercel)
• hono/middleware barrel import (usa sotto-percorso per middleware)
• c.req.headers() / c.req.body() / c.req.signal() metodi accessor (usa c.req.raw.*)
• FC con figli impliciti (usa PropsWithChildren<P>)
• app.fire() (deprecato dalla v4.8.0; usa fire(app) da hono/service-worker)
• import { Hono } from 'https://deno.land/x/hono/mod.ts' su Deno (obsoleto dalla v4.4.0; usa jsr:@hono/hono)

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())
• import cors from 'cors' da npm (usa hono/cors)
• supertest per test (usa app.request() / testClient(app))
• c.req.body già parsato (è un ReadableStream)
• c.req.parseBody() per JSON (solo form / multipart)
• c.req.text() poi c.req.json() (body consumato due volte)
• c.userId = ... assegnazione inline (usa c.set('userId', ...) con Variables tipizzate)

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)
• new Response(JSON.stringify(...)) in route RPC (il client vede unknown)
• hc<AppType>('/') URL relativo (lancia su $url())
• Importazione per valore dell'app server nel bundle client (trascina drizzle-orm, fs, dipendenze native - la trappola #1 del bundle RPC)
• Middleware senza createMiddleware<Env> (i tipi di Variables non si propagano)

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() / .first() / .all() non await (insert annullato quando il worker termina)
• Aggiornamento WebSocket senza Durable Object per inoltro (lo stato scompare)

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() / cache() su GET statici
• Segreto JWT hard-coded come stringa (perde tramite bundle)
• Costruzione di grande JSON in memoria invece di streamText (limite 128MB di Workers)

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: