@beignet/next 0.0.19 → 0.0.21

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @beignet/next
 
+## 0.0.21
+
+### Patch Changes
+
+- Ship TanStack Intent agent skills with Beignet packages and scaffold generated apps with Intent skill-loading guidance.
+  - @beignet/web@0.0.21
+
+## 0.0.20
+
+### Patch Changes
+
+- @beignet/web@0.0.20
+
 ## 0.0.19
 
 ### Patch Changes

package/README.md

@@ -32,6 +32,13 @@ npm install @beignet/next @beignet/core next
 
 This package requires TypeScript 5.0 or higher for proper type inference.
 
+## Agent skills
+
+This package ships a TanStack Intent skill for coding agents:
+`@beignet/next#routes-server`. Load it when wiring route groups, central route
+registration, `createNextServer`, server context, OpenAPI/devtools routes,
+Next catch-all API adapters, uploads, webhooks, or outbox drain routes.
+
 ## Quick start
 
 ### 1. Define your contracts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/next",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "type": "module",
   "description": "Next.js server-side handlers for Beignet",
   "main": "./dist/index.js",
@@ -17,6 +17,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.test-d.ts",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -34,7 +35,8 @@
     "typescript",
     "next",
     "nextjs",
-    "standard-schema"
+    "standard-schema",
+    "tanstack-intent"
   ],
   "license": "MIT",
   "repository": {
@@ -57,7 +59,7 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0"
   },
   "dependencies": {
-    "@beignet/web": "^0.0.19",
+    "@beignet/web": "^0.0.21",
     "@standard-schema/spec": "^1.0.0"
   },
   "devDependencies": {

package/skills/routes-server/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: routes-server
+description: "Build Beignet Next.js server integration with @beignet/next: defineRouteGroup, defineRoutes, contractsFromRoutes, createNextServer, server context, hooks, OpenAPI/devtools routes, catch-all API adapters, uploads, webhooks, outbox drains, and route inspection. Use when wiring or debugging Beignet routes in a Next app."
+---
+
+# Beignet Next Routes And Server
+
+Use this skill when working in a Next.js app that depends on `@beignet/next`.
+Read local `AGENTS.md`, `beignet.config.*`, and existing route/server files
+before changing code.
+
+## Route Shape
+
+Feature route groups live beside the feature and map contracts to use cases.
+
+```ts
+import { defineRouteGroup } from "@beignet/next";
+import type { AppContext } from "@/app-context";
+import { createProject, getProject } from "@/features/projects/contracts";
+import {
+  createProjectUseCase,
+  getProjectUseCase,
+} from "@/features/projects/use-cases";
+import { auth } from "@/lib/route-auth";
+
+export const projectRoutes = defineRouteGroup<AppContext>()({
+  name: "projects",
+  routes: [
+    {
+      contract: createProject,
+      hooks: [auth.required()],
+      useCase: createProjectUseCase,
+    },
+    {
+      contract: getProject,
+      useCase: getProjectUseCase,
+      input: ({ path }) => ({ id: path.id }),
+    },
+  ],
+});
+```
+
+Keep route entries thin: hooks, input mapping, policy checks, and use-case
+binding. Business behavior belongs in use cases.
+
+## Central Registry
+
+Register feature route groups once in `server/routes.ts`.
+
+```ts
+import { contractsFromRoutes, defineRoutes } from "@beignet/next";
+import type { AppContext } from "@/app-context";
+import { projectRoutes } from "@/features/projects/routes";
+
+export const routes = defineRoutes<AppContext>([projectRoutes]);
+export const contracts = contractsFromRoutes(routes);
+```
+
+OpenAPI, typed clients, devtools, and route inspection should derive from this
+registry. If a route is missing from OpenAPI or clients, check this file first.
+
+## Server Composition
+
+`server/index.ts` owns runtime composition:
+
+- `createNextServer(...)`
+- app ports
+- providers
+- hooks
+- server context blueprint
+- route registry
+- response validation and error mapping
+
+Keep app-specific infra wiring in `infra/` and `server/providers.ts`, not in
+feature route files.
+
+## Next Route Adapter
+
+Application API routes usually use one catch-all file:
+
+```ts
+import { server } from "@/server";
+
+export const DELETE = server.api;
+export const GET = server.api;
+export const HEAD = server.api;
+export const OPTIONS = server.api;
+export const PATCH = server.api;
+export const POST = server.api;
+export const PUT = server.api;
+```
+
+The catch-all file is adapter glue. Contracts should still use explicit paths
+such as `/projects/:id`, not catch-all contract patterns.
+
+## Focused Routes
+
+Focused route files are appropriate for framework helpers and specialized
+HTTP surfaces:
+
+- OpenAPI or Swagger UI
+- devtools
+- uploads
+- storage object routes
+- payment or webhook adapters
+- outbox drains
+- redirects or downloads
+
+Use a route `handle` escape hatch only when the route intentionally returns a
+native `Response`, streams, owns custom headers, or otherwise sits outside the
+normal use-case binder.
+
+## Context
+
+`server/context.ts` should use `defineServerContext`. Request context reads the
+session, creates an actor, attaches ports, request IDs, and trace context.
+Service context is for schedules, tasks, outbox drains, and background work;
+create a service actor and do not assume a request session.
+
+## Debugging
+
+- Route group exists but does not run: register it in `server/routes.ts`.
+- Contract missing from OpenAPI: export `contracts = contractsFromRoutes(routes)`.
+- `doctor` dislikes the route shape: use `defineRouteGroup<AppContext>()({ ... })`.
+- Client code imports `server/`: move shared DTOs to schemas and call through
+  contracts and the typed client.
+
+Run:
+
+```bash
+beignet routes
+beignet lint
+beignet doctor --strict
+```