roninforge-hono

Plugin Cursor pour Hono v4 (framework web TypeScript edge) + TypeScript. Épinglé à 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+). Enseigne les API v4 que les LLM entraînés sur des données antérieures à 2024 ne connaissent pas (c.json() toujours typé, le validateur lance HTTPException, getCookie/setCookie depuis hono/cookie, c.env en tant que propriété, streamText depuis hono/streaming, showRoutes depuis hono/dev, getRuntimeKey depuis hono/adapter, fire(app) depuis hono/service-worker, liaison Workers Static Assets à la place de serveStatic déprécié, JSR @hono/hono pour Deno). Détecte plus de 50 régressions LLM avec des paires MAUVAIS / CORRECT TypeScript.

Aucune version Hono v5 n'existe. La dernière stable est v4.12.19. Toute mention de « v5 » dans le code généré est une hallucination.

Le problème

Les mainteneurs de Hono eux-mêmes ont ouvert le numéro #3906 (« fichier llm.txt ») et le numéro #4812 (« Compétence officielle d'agent IA pour Hono ») explicitement parce que « les LLM n'ont pratiquement aucune connaissance du fonctionnement de la dernière version de Hono. » Les données d'entraînement antérieures à 2025 datent de l'ère v3. Les LLM génèrent :

API supprimées de v3 vers v4

• c.jsonT() au lieu de c.json() (toujours typé depuis v4.0.0)
• c.stream() / c.streamText() en tant que méthodes de Context (déplacées dans hono/streaming en v4)
• c.env() forme fonction (maintenant propriété ; détection de l'exécution via getRuntimeKey() depuis hono/adapter)
• c.req.cookie() (supprimé ; utiliser getCookie(c) depuis hono/cookie)
• app.showRoutes(), app.routerName (déplacés dans hono/dev)
• addEventListener('fetch') + app.handleEvent() (syntaxe Service Worker ; utiliser export default { fetch: app.fetch })
• app.head(...) routes (HEAD dérivé automatiquement de GET en v4)
• hono/nextjs import (utiliser hono/vercel)
• hono/middleware import baril (utiliser le sous-chemin par middleware)
• c.req.headers() / c.req.body() / c.req.signal() méthodes accesseurs (utiliser c.req.raw.*)
• FC avec enfants implicites (utiliser PropsWithChildren<P>)
• app.fire() (déprécié v4.8.0 ; utiliser fire(app) depuis hono/service-worker)
• import { Hono } from 'https://deno.land/x/hono/mod.ts' sur Deno (obsolète depuis v4.4.0 ; utiliser jsr:@hono/hono)

Fuites Express / Koa / Fastify (la plus grande classe)

• return manquant sur c.json() (résout en undefined ; v4 lève « Context is not finalized »)
• res.json() / res.send() au lieu de c.json() (pas de res dans Hono)
• (req, res, next) signature de middleware (utiliser (c, next))
• (err, req, res, next) middleware d'erreur (utiliser app.onError + HTTPException)
• app.use(express.json()) analyseur de corps (Hono analyse à la demande via c.req.json())
• import cors from 'cors' depuis npm (utiliser hono/cors)
• supertest pour les tests (utiliser app.request() / testClient(app))
• c.req.body déjà parsé (c'est un ReadableStream)
• c.req.parseBody() pour du JSON (uniquement formulaire / multipart)
• c.req.text() puis c.req.json() (corps consommé deux fois)
• c.userId = ... affectation en ligne (utiliser c.set('userId', ...) avec Variables typées)

Erreurs TypeScript / inférence RPC

• new Hono() sans génériques Bindings / Variables (c.env est {})
• Routes définies en tant qu'instructions (app.get(...) puis app.post(...)) - perd les types RPC
• Sous-app app.route() appel en tant qu'instruction - même règle
• Contrôleurs de style Rails passant Context (perd l'inférence du paramètre de chemin, selon les meilleures pratiques de Hono)
• app.use('/path', zValidator(...)) au lieu de comme argument de route (erreur TS : « 'json' not assignable to 'never' »)
• c.notFound() dans les routes consommées par RPC (ne peut pas typer côté client)
• new Response(JSON.stringify(...)) dans les routes RPC (le client voit unknown)
• hc<AppType>('/') URL relative (lève une erreur sur $url())
• Import par valeur de l'application serveur dans le bundle client (entraîne drizzle-orm, fs, dépendances natives – le piège n°1 du gonflement de bundle RPC)
• Middleware sans createMiddleware<Env> (les types Variables ne se propagent pas)

Pièges Cloudflare Workers

• process.env.X dans le code Workers (undefined ; utiliser c.env.X avec Bindings typés)
• Imports fs / path dans Workers (pas de système de fichiers)
• compatibility_flags: ["node_compat"] indicateur obsolète (utiliser nodejs_compat)
• serveStatic déprécié depuis hono/cloudflare-workers (depuis v4.3.0 ; utiliser la liaison d'actifs)
• c.executionCtx.waitUntil() manquant pour du fire-and-forget
• Vérification de vérité if (c.executionCtx) (le getter lève une exception sur Bun et Next.js App Router)
• Appels D1 non attendus .run() / .first() / .all() (l'insertion est annulée lorsque le worker se termine)
• Mise à niveau WebSocket sans transfert Durable Object (l'état disparaît)

Lacunes de sécurité / production

• Pas de middleware secureHeaders()
• Pas de csrf() sur les mutations authentifiées par cookie
• cors({ origin: '*', credentials: true }) (les navigateurs abandonnent silencieusement ; AJAX échoue)
• bodyLimit() manquant sur les routes POST / PUT et épingler hono >= 4.9.7 pour CVE-2025-59139
• Cookies sans httpOnly / secure / sameSite / path
• sameSite: 'None' sans secure: true (abandonné silencieusement)
• Middleware de journalisation du corps sans masquage (fuite de mots de passe / tokens / données personnelles)
• Pas de etag() / cache() sur les GET statiques
• Secret JWT codé en dur (fuit via le bundle)
• Construction d'un gros JSON en mémoire au lieu de streamText (limite de 128 Mo des Workers)

Bugs de routage / structure

• Gestionnaire notFound de sous-app (code mort ; seul le niveau supérieur se déclenche)
• Incohérence de la barre oblique finale (/users vs /users/ sont des routes différentes par défaut)
• await next() plus d'une fois (double le travail aval)
• Chevauchement app.use(prefix, mw) + app.route(prefix, subApp) (le middleware se déclenche deux fois)
• app.basePath('/api') en tant qu'instruction (le préfixe est jeté du type)

Exécution silencieusement erronée

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

Problèmes réels plus petits

• c.req.query() sans argument en attendant une valeur unique
• c.req.param('id') dans un middleware global (undefined là où :id n'est pas dans le chemin)
• OpenAPI fait maison sans @hono/zod-openapi
• cors() monté APRÈS les routes (ne correspond jamais)

Pourquoi ce plugin (comparé aux règles Hono communautaires existantes)

Quelques règles Hono existent déjà sur cursor.directory et dans awesome-cursorrules (PR #152) : elles couvrent les retours de c.json(), zValidator + Zod, c.env pour les Workers, les routes chaînées pour RPC, et l'export app.fetch pour les Workers. Elles présentent trois problèmes structurels que ce plugin corrige :