{
  "$schema": "https://hyperjs.ai/schema/registry-item.json",
  "name": "agent-rules",
  "version": "0.1.0",
  "description": "Cursor / Claude Code rules teaching AI assistants how to compose Hyper routes, plugins, and middleware correctly.",
  "readme": "# agent-rules\n\nDrops `.cursor/rules/hyper.md` and `AGENTS.md` into your repo so Cursor, Claude\nCode, and other AI assistants understand how Hyper apps are structured: the\nchain API on `Hyper`, the explicit `route.<verb>().handle()` builder, the\n`decorate()` typing flow, plugin authoring, and the secure-by-default posture.\n\n```bash\nhyper add agent-rules\n```\n\nAfter install, AI agents get the rules automatically — no extra setup.\n",
  "registryDeps": [],
  "peerDeps": {},
  "optionalPeerDeps": {},
  "files": [
    {
      "path": ".cursor/rules/hyper.md",
      "contents": "---\ndescription: How to write Hyper routes, plugins, and middleware in this repo\nglobs:\n  - src/hyper/**/*.ts\n  - src/**/*.ts\nalwaysApply: true\n---\n\n# Hyper rules\n\nThis project uses [Hyper](https://hyperjs.ai), a Bun-first API framework whose\nsource code lives in this repository at `src/hyper/<component>/`. Imports use\nthe `@hyper/*` alias (mapped via `tsconfig.json` `paths`).\n\n## Authoring routes\n\nTwo equivalent styles. Prefer the chain API for app composition; prefer the\nbuilder for routes you want to attach middleware/decorators/types to.\n\n### Chain API (preferred for top-level apps)\n\n```ts\nimport { Hyper, ok } from \"@hyper/core\"\nimport { z } from \"zod\"\n\nexport default new Hyper()\n  .get(\"/health\", \"OK\")\n  .post(\n    \"/users\",\n    { body: z.object({ name: z.string(), email: z.email() }) },\n    ({ body }) => ok({ id: crypto.randomUUID(), ...body }),\n  )\n  .listen(3000)\n```\n\n### Route builder (preferred when you need typed responses + middleware)\n\n```ts\nimport { ok, route, notFound } from \"@hyper/core\"\nimport { z } from \"zod\"\n\nconst UserParams = z.object({ id: z.string() })\n\nexport const getUser = route\n  .get(\"/users/:id\")\n  .params(UserParams)\n  .handle(async ({ params, ctx }) => {\n    const u = await ctx.store.get(params.id)\n    if (!u) return notFound({ code: \"user_not_found\" })\n    return ok(u)\n  })\n```\n\n## Composing apps with `.use()`\n\n`.use()` is polymorphic. It accepts:\n\n- A sub-`Hyper` instance — its prefix is honored\n- A `HyperApp` from `app({...})`\n- A raw `Route` value or array of routes\n- A plugin returned by a plugin factory (`hyperLog(...)`, `cors(...)`, etc.)\n- A plain middleware (object with `start`/`success`/`error`/`finish`)\n\n```ts\nimport { Hyper } from \"@hyper/core\"\nimport { hyperLog } from \"@hyper/log\"\nimport { cors } from \"@hyper/cors\"\nimport users from \"./routes/users.ts\"\nimport posts from \"./routes/posts.ts\"\n\nexport default new Hyper()\n  .use(hyperLog({ service: \"api\" }))\n  .use(cors({ origin: [\"https://example.com\"] }))\n  .use(users)            // honors `users`'s own prefix\n  .use(\"/v1\", posts)     // re-prefix\n  .listen(3000)\n```\n\n## Decorating context\n\nUse `.decorate()` (or `decorate: [...]` in `app({...})`) to attach typed\nservices to `ctx`. Always extend `AppContext` via module augmentation so\nhandlers see the right types.\n\n```ts\nimport { Hyper } from \"@hyper/core\"\nimport { db } from \"./db.ts\"\n\ndeclare module \"@hyper/core\" {\n  interface AppContext {\n    readonly db: typeof db\n  }\n}\n\nexport default new Hyper().decorate(() => ({ db }))\n```\n\n## Response helpers\n\nAlways return through helpers — they project to OpenAPI/MCP/client-types\ncorrectly. Never `new Response()` directly.\n\n```ts\nimport {\n  ok, created, accepted, noContent,\n  badRequest, unauthorized, forbidden, notFound, conflict, unprocessable, tooManyRequests,\n  redirect, html, text, sse, stream, file,\n} from \"@hyper/core\"\n```\n\n## Errors\n\nThrow `HyperError` for typed errors — they project to the route's `errors`\nunion and serialize consistently.\n\n```ts\nimport { createError } from \"@hyper/core\"\n\nthrow createError({ status: 409, code: \"duplicate_email\", message: \"Email already in use\" })\n```\n\n## Validation\n\nBody / params / query schemas are Standard Schema-compatible: Zod, Valibot,\nArkType all work. Schemas declared on a route project to OpenAPI input\nschemas automatically.\n\n## Secure-by-default — do NOT disable lightly\n\nHyper sets these for every response unless explicitly turned off:\n\n- `x-content-type-options: nosniff`\n- `x-frame-options: DENY`\n- `referrer-policy: strict-origin-when-cross-origin`\n- `strict-transport-security` (production only)\n- 1MB body cap\n- prototype-pollution guards on JSON bodies\n- per-route timeouts\n\nAuth endpoints default to rate-limiting via `@hyper/rate-limit`. JWT secrets\nmust be ≥32 bytes (`@hyper/auth-jwt` will refuse to start otherwise).\n\n## Testing\n\nUse `@hyper/testing` — `app.test()`, `call()`, memory stores, deterministic\nclocks. Tests should run against `app.fetch(new Request(...))` directly,\nno network.\n\n```ts\nimport { describe, expect, test } from \"bun:test\"\nimport app from \"../src/app.ts\"\n\ndescribe(\"users\", () => {\n  test(\"GET /users/:id\", async () => {\n    const res = await app.fetch(new Request(\"http://localhost/users/u1\"))\n    expect(res.status).toBe(200)\n  })\n})\n```\n\n## File layout convention\n\n```\nsrc/\n  hyper/                 # Hyper framework source (managed by `hyper` CLI)\n    core/                # @hyper/core\n    log/                 # @hyper/log\n    cors/                # @hyper/cors\n    ...\n  app.ts                 # entrypoint; default-exports a Hyper instance or HyperApp\n  routes/                # sub-app modules (preferred over inline routes)\n  schemas/               # Zod / Valibot schemas\n```\n\n`src/hyper/` is owned by the registry — do not edit by hand unless you intend\nto fork that component (and accept that `hyper update` will conflict). Run\n`hyper diff` to inspect drift between your local copy and the upstream\nregistry.\n",
      "sha256": "10d849a3ab7b53790b7e021d5a941f4224f3c679f9da5f1f076474fe2b9a5d24",
      "target": "@root/.cursor/rules/hyper.md"
    },
    {
      "path": "AGENTS.md",
      "contents": "# AGENTS.md\n\nGuidance for AI coding agents working in this repository.\n\nThis project uses [Hyper](https://hyperjs.ai), a Bun-first API framework. The\nframework source is **vendored into this repo** under `src/hyper/<component>/`\nand managed by the `hyper` CLI — components are installed from a registry and\ncopied directly into the project, not pulled in as npm dependencies. You own\nthe code; you can edit it freely; `hyper update` will pull upstream changes\nwhen you ask for them.\n\n## Quick orientation\n\n- `src/app.ts` — entrypoint. Default-exports a `Hyper` instance or `HyperApp`.\n- `src/hyper/core/` — framework runtime. Imports as `@hyper/core`.\n- `src/hyper/<plugin>/` — installable plugins (log, cors, auth-jwt, …). Each is\n  imported as `@hyper/<plugin>`.\n- `package.json` has **no `@usehyper/*` deps** — everything ships via the\n  registry.\n- `hyper.config.json` — the registry config (URL, baseDir, alias).\n- `hyper.lock.json` — pins each installed component's version + per-file hash.\n\n## When you write code\n\n1. Import from `@hyper/<component>` — never `@usehyper/<component>`.\n2. Always return through Hyper's response helpers (`ok`, `created`, `notFound`, …).\n3. Always declare schemas (`body`, `params`, `query`) — they project to\n   OpenAPI/MCP/client types automatically.\n4. Use `.decorate()` for typed services on `ctx`. Augment `AppContext` via\n   `declare module \"@hyper/core\"`.\n5. For protected routes, chain `.auth()` from `@hyper/auth-jwt`.\n6. Never weaken the secure-by-default headers without an explicit reason.\n\n## When you install components\n\nUse the CLI, not edits:\n\n```bash\nhyper add cors\nhyper add auth-jwt\nhyper add openapi openapi-zod\nhyper diff log              # inspect drift\nhyper update log            # bump to latest registry version\nhyper add --info session    # show readme/files/deps without installing\n```\n\nThe CLI rewrites `@hyper/*` imports to whatever alias is configured in\n`hyper.config.json`. Do not hand-edit the `paths` mapping.\n\n## When you debug or extend\n\n- `hyper routes` — print the route graph\n- `hyper openapi` — emit OpenAPI 3.1\n- `hyper client out.ts` — emit a typed RPC client\n- `hyper mcp` — serve the app's routes over MCP for AI introspection\n- `hyper bench --tests` — measure per-route latency\n\n## Style\n\n- Imports use `.ts` extensions (`from \"./schemas.ts\"`) — `verbatimModuleSyntax`\n  is on.\n- Prefer the chain API (`new Hyper().get(...)`) for top-level apps; prefer\n  the builder (`route.get(...).body(...).handle(...)`) for sub-app modules.\n- Tests run via `bun test` against `app.fetch(new Request(...))` — no network.\n",
      "sha256": "8b6b968951c70d27234e5642b2636be927bdff7e611fa86a2b1cb6a8f67e9446",
      "target": "@root/AGENTS.md"
    }
  ],
  "subpaths": {},
  "title": "Agent rules",
  "docs": "Files installed:\n  - AGENTS.md (project root)\n  - .cursor/rules/hyper.md\n\nKeep these committed so AI assistants pick up Hyper's conventions automatically. Re-run `hyper add agent-rules` after upgrading Hyper to refresh."
}