roninforge-hono

Cursor plugin for Hono v4 (TypeScript edge web framework) + TypeScript. Pinned to 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+). Teaches the v4 APIs that LLMs trained on pre-2024 data do not know (c.json() always typed, validator throws HTTPException, getCookie/setCookie from hono/cookie, c.env as property, streamText from hono/streaming, showRoutes from hono/dev, getRuntimeKey from hono/adapter, fire(app) from hono/service-worker, Workers Static Assets binding instead of deprecated serveStatic, JSR @hono/hono for Deno). Catches 50+ LLM regressions with BAD / CORRECT TypeScript pairs.

No Hono v5 exists. Latest stable is v4.12.19. Any "v5" in generated code is hallucination.

The Problem

Hono's own maintainers filed Issue #3906 ("llm.txt file") and Issue #4812 ("Official AI Agent Skill for Hono") explicitly because "LLMs have basically no knowledge of how the latest Hono works." Pre-2025 training data is v3-era. LLMs emit:

v3 -> v4 removed APIs

• c.jsonT() instead of c.json() (always typed since v4.0.0)
• c.stream() / c.streamText() as Context methods (moved to hono/streaming in v4)
• c.env() function form (now property; runtime detection via getRuntimeKey() from hono/adapter)
• c.req.cookie() (removed; use getCookie(c) from hono/cookie)
• app.showRoutes(), app.routerName (moved to hono/dev)
• addEventListener('fetch') + app.handleEvent() (Service Worker syntax; use export default { fetch: app.fetch })
• app.head(...) routes (HEAD auto-derived from GET in v4)
• hono/nextjs import (use hono/vercel)
• hono/middleware barrel import (use per-middleware subpath)
• c.req.headers() / c.req.body() / c.req.signal() accessor methods (use c.req.raw.*)
• FC with implicit children (use PropsWithChildren<P>)
• app.fire() (deprecated v4.8.0; use fire(app) from hono/service-worker)
• import { Hono } from 'https://deno.land/x/hono/mod.ts' on Deno (stale since v4.4.0; use jsr:@hono/hono)

Express / Koa / Fastify leakage (the biggest class)

• Missing return on c.json() (resolves to undefined; v4 throws "Context is not finalized")
• res.json() / res.send() instead of c.json() (no res in Hono)
• (req, res, next) middleware signature (use (c, next))
• (err, req, res, next) error middleware (use app.onError + HTTPException)
• app.use(express.json()) body parser (Hono parses on demand via c.req.json())
• import cors from 'cors' from npm (use hono/cors)
• supertest for tests (use app.request() / testClient(app))
• c.req.body as already parsed (it's a ReadableStream)
• c.req.parseBody() for JSON (only form / multipart)
• c.req.text() then c.req.json() (body consumed twice)
• c.userId = ... inline assignment (use c.set('userId', ...) with typed Variables)

TypeScript / RPC inference mistakes

• new Hono() without Bindings / Variables generics (c.env is {})
• Routes defined as statements (app.get(...) then app.post(...)) - drops RPC types
• Sub-app app.route() calls as statements - same rule
• Rails-style controllers passing Context around (loses path-param inference, per Hono Best Practices)
• app.use('/path', zValidator(...)) instead of as route arg (TS error: 'json' not assignable to 'never')
• c.notFound() in RPC-consumed routes (cannot type on client)
• new Response(JSON.stringify(...)) in RPC routes (client sees unknown)
• hc<AppType>('/') relative URL (throws on $url())
• Value-import of server app into client bundle (drags drizzle-orm, fs, native deps - the #1 RPC bundle-bloat pitfall)
• Middleware without createMiddleware<Env> (Variables types do not propagate)

Cloudflare Workers gotchas

• process.env.X in Workers code (undefined; use c.env.X with typed Bindings)
• fs / path imports in Workers (no filesystem)
• compatibility_flags: ["node_compat"] legacy flag (use nodejs_compat)
• Deprecated serveStatic from hono/cloudflare-workers (since v4.3.0; use asset binding)
• Missing c.executionCtx.waitUntil() for fire-and-forget
• Truthy-check if (c.executionCtx) (getter throws on Bun and Next.js App Router)
• Unawaited D1 .run() / .first() / .all() (insert cancelled when worker terminates)
• WebSocket upgrade without Durable Object forwarding (state vanishes)

Security / production gaps

• No secureHeaders() middleware
• No csrf() on cookie-authenticated mutations
• cors({ origin: '*', credentials: true }) (browsers silently drop; AJAX fails)
• Missing bodyLimit() on POST / PUT routes and pin hono >= 4.9.7 for CVE-2025-59139
• Cookies without httpOnly / secure / sameSite / path
• sameSite: 'None' without secure: true (silently dropped)
• Body-logging middleware without redaction (passwords / tokens / PII leak)
• No etag() / cache() on static GETs
• Hard-coded JWT secret string (leaks via bundle)
• Building large JSON in memory instead of streamText (Workers 128MB cap)

Routing / structural bugs

• Sub-app notFound handler (dead code; only top-level fires)
• Trailing-slash inconsistency (/users vs /users/ are different routes by default)
• await next() more than once (doubles downstream work)
• app.use(prefix, mw) + app.route(prefix, subApp) overlap (middleware fires twice)
• app.basePath('/api') as statement (prefix is thrown away from the type)

Runtime quietly-wrong

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

Smaller real issues

• c.req.query() with no arg when expecting single value
• c.req.param('id') in global middleware (undefined where :id isn't in path)
• Hand-rolled OpenAPI without @hono/zod-openapi
• cors() mounted AFTER routes (never matches)

Why this plugin (vs the existing community Hono rules)

A handful of Hono rules already live on cursor.directory and in awesome-cursorrules (PR #152): they cover c.json() returns, zValidator + Zod, c.env for Workers, chained routes for RPC, and app.fetch Workers export. They have three structural problems this plugin fixes:

1. They do NOT cover the v3 -> v4 removed APIs. LLMs continue to emit c.jsonT, c.stream, c.env(), c.req.cookie, app.showRoutes, the hono/middleware barrel, and app.handleEvent - all removed in v4.0.0 (2024-02). Existing rules silently allow them.
2. They omit the Express-leakage class. (req, res, next), (err, req, res, next), npm cors, app.use(express.json()), supertest, missing return on c.json - all happen constantly in LLM-generated Hono code. Existing rules treat them as one-offs.
3. They miss security defaults and the CVE pin. None enforce secureHeaders() / csrf(); none mention bodyLimit CVE-2025-59139 (fix in v4.9.7); none address RPC client pitfalls (relative URL, value-import leakage, c.notFound typing).

This plugin ships: