@remix-run/cli 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remix-run/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Command-line interface for Remix",
   "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
@@ -31,14 +31,14 @@
   },
   "dependencies": {
     "semver": "^7.7.4",
-    "@remix-run/test": "^0.4.2",
-    "@remix-run/terminal": "^0.1.1"
+    "@remix-run/terminal": "^0.1.1",
+    "@remix-run/test": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
     "@types/semver": "^7.5.8",
     "@typescript/native-preview": "7.0.0-dev.20251125.1",
-    "@remix-run/assert": "^0.2.1"
+    "@remix-run/assert": "^0.3.0"
   },
   "keywords": [
     "remix",

package/template/.agents/skills/remix/SKILL.md

@@ -9,7 +9,7 @@ Use this skill for end-to-end Remix app work. This skill helps you choose the ri
 
 ## Full Package Documentation
 
-This skill is the quick guide. When you need fuller API documentation, examples, or package-specific details for a `remix/*` subpath, first look for a README next to the relevant generated source file in the published `remix` package: `node_modules/remix/src/<subpath>/README.md`. If that README does not exist, look for the nearest parent README because some subpaths share their parent package documentation.
+This skill is the quick guide. When you need fuller API documentation, examples, or package-specific details for a `remix/*` subpath, first look for a README next to the relevant generated source file in the published `remix` package: `node_modules/remix/src/<subpath>/README.md`. These published README files are generated mirrors; in the Remix source repository, the canonical README lives in the owning `packages/*` package and the `packages/remix/src/**/README.md` mirrors are intentionally ignored. If that README does not exist, look for the nearest parent README because some subpaths share their parent package documentation.
 
 Examples:
 
@@ -71,7 +71,7 @@ Common bundles:
 2. **Start from the server contract.** Add or update `app/routes.ts` before wiring handlers or UI.
 3. **Put code in the narrowest owner.** Favor route-local code first, then promote only when reuse is real.
 4. **Make the server path correct before adding browser behavior.** A route should return the right `Response` via `router.fetch(...)` before you add `clientEntry(...)`, animations, or DOM effects.
-5. **Add middleware deliberately.** Keep fast-exit middleware early and request-enriching middleware later. Export a typed `AppContext` from the root middleware stack and use it in controllers.
+5. **Add middleware deliberately.** Keep fast-exit middleware early and request-enriching middleware later. Export a typed `AppContext` from the middleware stack and use it in controllers.
 6. **Validate input at the boundary.** Parse and validate `Request`, `FormData`, params, cookies, and external payloads before they reach rendering or persistence logic.
 7. **Hydrate only when necessary.** Prefer server-rendered UI. Use `clientEntry(...)` and `run(...)` only for real browser interactivity or browser-only APIs.
 8. **Test the narrowest meaningful layer.** Prefer router tests for route behavior. Use component tests when the behavior is truly interactive or DOM-specific.
@@ -113,7 +113,7 @@ When code could live in multiple places:
 
 - Put top-level leaf actions in `app/actions/controller.tsx`
 - A controller's `actions` object contains only direct leaf route keys from the route map passed to `router.map(...)`
-- Add `app/actions/<route-key>/controller.tsx` for each nested route map that needs actions or middleware, and map it explicitly with `router.map(routes.<routeKey>, controller)`
+- Add `app/actions/<route-key>/controller.tsx` for each nested route map that needs actions or controller middleware, and map it explicitly with `router.map(routes.<routeKey>, controller)`
 - Name directories under `app/actions/` after route-map keys, not URL path segments
 - Keep route-local UI and helpers next to the controller that owns them
 - Move shared cross-route UI to `app/ui/`
@@ -135,7 +135,7 @@ When code could live in multiple places:
 - Do not create standalone root action files; put root route actions in `app/actions/controller.tsx`
 - Do not put nested route-map keys in a controller's `actions`
 - Do not register normal app leaf routes directly in `app/router.ts` when they belong in a controller
-- Do not rely on middleware from one controller to protect another controller; map middleware explicitly in each controller that needs it
+- Do not rely on controller middleware from one controller to protect another controller; add controller middleware explicitly in each controller that needs it
 - Do not put middleware or persistence helpers in `app/utils/` when they have a clearer home
 
 ## Core Remix Rules
@@ -147,7 +147,7 @@ When code could live in multiple places:
 - Model HTTP behavior explicitly. Status codes, headers, redirects, cache rules, and content types are part of the route contract
 - Make the server route correct first. A POST should already return the right HTML, redirect, or error response on its own before `clientEntry(...)` layers interactivity on top
 - Validate input at the boundary using `remix/data-schema` (and `remix/data-schema/form-data` for forms). `parseSafe` makes the failure path a return value instead of an exception
-- Derive `AppContext` from the root middleware stack so `get(Database)`, `get(Session)`, `get(Auth)`, and similar keys stay typed. If the controller never reads from context, it doesn't need the harness
+- Derive `AppContext` from the middleware stack so `get(Database)`, `get(Session)`, `get(Auth)`, and similar keys stay typed. If the controller never reads from context, it doesn't need the harness
 - Outside actions and controllers, only use `getContext()` when `asyncContext()` is in the middleware stack
 - Remix Component is not React: write `function Name(handle: Handle<Props>) { return () => ... }`, read props from `handle.props`, keep state in setup-scope variables, call `handle.update()` explicitly, and do DOM-sensitive work in event handlers or `queueTask(...)`, not in render
 - Prefer host-element mixins via `mix={mixin(...)}` for behavior and styling instead of inventing custom host prop conventions. Use `mix={[...]}` only when composing multiple mixins
@@ -202,14 +202,14 @@ Use this map to find the right package quickly. Each entry says what the package
 
 ### Routing, Server, and Responses
 
-- `remix/router` — the router itself. Use for `createRouter`, controller and middleware types, and registering routes
+- `remix/router` — the router itself. Use for `createRouter`, controllers, middleware types, and registering routes
 - `remix/routes` — declarative route builders. Use for `route`, `get`, `post`, `put`, `del`, `form`, `resources` when defining `app/routes.ts`
 - `remix/node-fetch-server` — default Node adapter for new apps. Use `createRequestListener` with `node:http`, `node:https`, or `node:http2` in `server.ts` when booting the template-style app
 - `remix/assets` — browser asset server. Use for `createAssetServer` when serving compiled scripts and styles, getting public hrefs, and emitting preloads. Configure a `basePath`, and keep `fileMap` URL patterns relative to it. Shared compiler options such as `target`, `sourceMaps`, `sourceMapSourcePaths`, and `minify` live at the top level
 - `remix/headers` — `SuperHeaders` plus typed header parsers and builders. Use the default export when you want a `Headers` subclass with typed accessors like `headers.contentType`, `headers.cacheControl`, and `headers.setCookie`; use named classes such as `CacheControl`, `ContentDisposition`, and `Vary` when working with individual header values
 - `remix/response/redirect` — `redirect(href, status?)`. Use for the canonical "POST then redirect" pattern and other location changes
 - `remix/response/html` — `createHtmlResponse`. Use when you need an HTML `Response` from a string or stream without rendering through `remix/ui`
-- `remix/response/compress` — `compressResponse`. Use when compressing one-off responses outside the global `compression()` middleware
+- `remix/response/compress` — `compressResponse`. Use when compressing one-off responses outside `compression()` middleware
 - `remix/response/file` — file-download responses. Use for `Content-Disposition: attachment` responses
 - `remix/route-pattern` — low-level URL matching and generation. Use `RoutePattern` or `createMatcher` when working with raw patterns outside the router. `href(...)` encodes pathname and search params for you, and `match(...)` returns decoded params
 - `remix/route-pattern/specificity` — pattern ranking helpers. Use only when building custom matcher or reporting logic outside the normal router/matcher APIs
@@ -232,7 +232,7 @@ Use this map to find the right package quickly. Each entry says what the package
 ### Auth, Sessions, and Cookies
 
 - `remix/session` — the `Session` object: `get`, `set`, `flash`, `unset`, `regenerateId`. Use for any per-browser state where tampering would be a bug (login, "I submitted this form already", cart, flash messages)
-- `remix/middleware/session` — `session(cookie, storage)`. Use to wire a session cookie and storage backend into the root middleware stack
+- `remix/middleware/session` — `session(cookie, storage)`. Use to wire a session cookie and storage backend into the middleware stack
 - `remix/session-storage/fs`, `remix/session-storage/memory`, `remix/session-storage/cookie` — storage backends. Use `fs-storage` for single-process apps, `memory-storage` for tests, `cookie-storage` for stateless deployments where data fits in a cookie
 - `remix/session-storage/redis` — Redis-backed storage. Use for multi-process or multi-host deployments
 - `remix/session-storage/memcache` — Memcache-backed storage. Same multi-host use case as Redis
@@ -258,7 +258,7 @@ Use this map to find the right package quickly. Each entry says what the package
 - `remix/middleware/form-data` — `formData()`. Use to parse `FormData` once and expose it via `get(FormData)` instead of calling `await request.formData()` in each action
 - `remix/form-data-parser` — lower-level `parseFormData`, `FileUpload`. Use when implementing custom upload handlers. Upload handler errors propagate directly
 - `remix/multipart-parser` and `remix/multipart-parser/node` — low-level multipart stream parsing. `MultipartPart.headers` is a plain object keyed by lower-case header name; read values with bracket notation such as `part.headers['content-type']`
-- `remix/middleware/compression` — `compression()`. Use globally for text-like responses
+- `remix/middleware/compression` — `compression()`. Use for text-like responses
 - `remix/middleware/logger` — `logger()`. Use in development for request logs; pass `colors` to force terminal color output on or off
 - `remix/middleware/method-override` — `methodOverride()`. Use when HTML forms need `PUT`, `PATCH`, or `DELETE`
 - `remix/middleware/async-context` — `asyncContext()`, `getContext()`. Use when helpers outside actions need request context without threading it through every call

package/template/.agents/skills/remix/references/auth-and-sessions.md

@@ -335,9 +335,9 @@ async function refreshGoogleTokens({ get }) {
 
 ## Protecting Routes
 
-### Controller-level protection
+### Controller middleware protection
 
-Apply `requireAuth()` to every action in one controller:
+Apply `requireAuth()` as controller middleware to every action in one controller:
 
 ```typescript
 import { createController } from 'remix/router'
@@ -389,7 +389,7 @@ export default createController(routes.admin, {
 })
 ```
 
-### Action-level protection
+### Action middleware protection
 
 Apply middleware to a single route:
 

package/template/.agents/skills/remix/references/middleware-and-server.md

@@ -4,7 +4,7 @@
 
 How to compose the request lifecycle and bridge the router to a runtime. Read this when the task involves:
 
-- Choosing or ordering built-in middleware in the root stack
+- Choosing or ordering built-in middleware in the stack
 - Writing custom middleware that sets typed context values
 - Adding fast-exit handling (static files, CORS preflights) versus request-enriching layers (sessions, auth, data loading)
 - Choosing when to keep the generated Node server versus switching server adapters
@@ -50,7 +50,7 @@ let router = createRouter({ middleware })
 | Middleware                 | Import                             | Use when                                                                      | Notes                                                          |
 | -------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | `staticFiles(dir, opts?)`  | `remix/middleware/static`          | Serve files from `public/` or another directory exactly as they exist on disk | Fast exit; usually near the top                                |
-| `compression()`            | `remix/middleware/compression`     | Compress text-like responses                                                  | Usually global                                                 |
+| `compression()`            | `remix/middleware/compression`     | Compress text-like responses                                                  | Usually app-wide                                               |
 | `logger()`                 | `remix/middleware/logger`          | Log requests and responses                                                    | Often development-only; `colors` can force color output on/off |
 | `cors(opts?)`              | `remix/middleware/cors`            | Endpoints must serve cross-origin browsers or preflight `OPTIONS` requests    | Usually early so preflights can short-circuit                  |
 | `cop(opts?)`               | `remix/middleware/cop`             | Reject unsafe cross-origin browser requests without synchronizer tokens       | Put before session or CSRF when used                           |
@@ -60,7 +60,7 @@ let router = createRouter({ middleware })
 | `csrf(opts?)`              | `remix/middleware/csrf`            | Session-backed form workflows need synchronizer-token CSRF protection         | Requires `session()` before it                                 |
 | `asyncContext()`           | `remix/middleware/async-context`   | Helpers outside handlers need request context via `getContext()`              | Add before helpers rely on it                                  |
 | `auth({ schemes })`        | `remix/middleware/auth`            | Resolve auth state into `context.get(Auth)`                                   | Run after `session()` for session-backed auth                  |
-| `requireAuth()`            | `remix/middleware/auth`            | A controller or action must reject anonymous access                           | Usually controller-level or action-level, not global           |
+| `requireAuth()`            | `remix/middleware/auth`            | A controller or action must reject anonymous access                           | Usually controller middleware or action middleware             |
 
 ### Static files vs browser modules
 
@@ -73,7 +73,7 @@ let router = createRouter({ middleware })
 - Parse request bodies before middleware that depends on them, such as `methodOverride()` and form field token extraction in `csrf()`
 - Run `session()` before `csrf()` and before session-backed `auth()`
 - Add `asyncContext()` before helpers or shared code call `getContext()`
-- Keep route protection like `requireAuth()` at controller or action scope unless the entire app is private
+- Keep route protection like `requireAuth()` as controller middleware or action middleware unless the entire app is private
 
 ### Common stacks
 
@@ -175,17 +175,17 @@ export function getCurrentUserSafely() {
 }
 ```
 
-## Middleware Layers
+## Middleware Types
 
-Middleware can be applied at three levels:
+Middleware has three API-owned forms:
 
-1. **Router-level** — runs for every request:
+1. **Router middleware** — runs for every request:
 
    ```typescript
-   let router = createRouter({ middleware: [...] })
+   let router = createRouter({ middleware: [logger(), session(cookie, storage)] })
    ```
 
-2. **Controller-level** — runs for the direct actions in one controller:
+2. **Controller middleware** — runs for the direct actions in one controller:
 
    ```typescript
    export default createController(routes.account, {
@@ -196,14 +196,19 @@ Middleware can be applied at three levels:
 
    Controller middleware does not flow into other controllers. Add the middleware to each controller that needs it.
 
-3. **Action-level** — runs for a single route:
+3. **Action middleware** — runs for a single action:
+
    ```typescript
    router.get(routes.account.index, {
      middleware: [requireAuth()],
-     handler: accountAction.handler,
+     handler(context) {
+       return render(<AccountPage identity={context.auth.identity} />)
+     },
    })
    ```
 
+Prefer inline arrays for `middleware` options. Use `RouterContext<typeof router>` to derive an app context from a router that uses inline middleware. Use `createMiddleware()` only when a chain is stored in a variable and its exact tuple type needs to be preserved, such as when deriving `MiddlewareContext<typeof rootMiddleware>` without a router value, exporting a reusable chain, or returning a chain from a factory.
+
 ## Node Server Setup
 
 New apps already include a `server.ts` that adapts the app router with `remix/node-fetch-server`. Keep that generated server unless the task specifically needs to change runtime behavior such as host/protocol handling, TLS, HTTP/2, WebSockets, deployment lifecycle, or test-only server setup.

package/template/.agents/skills/remix/references/routing-and-controllers.md

@@ -108,14 +108,17 @@ The handler receives a context object with:
 - `url` — the request URL
 - `request` — the raw `Request`
 
-Actions with inline middleware:
+Actions with action middleware:
 
 ```typescript
+import { createAction } from 'remix/router'
 import { requireAuth } from 'remix/middleware/auth'
 
-router.get(routes.account.index, {
+export const account = createAction(routes.account.index, {
   middleware: [requireAuth()],
-  handler: accountAction.handler,
+  handler(context) {
+    return render(<AccountPage />)
+  },
 })
 ```
 
@@ -305,7 +308,7 @@ router.map(routes.account.settings, accountSettingsController)
 
 ### Controller middleware
 
-The `middleware` array on a controller runs only for the direct actions in that controller, before action-level middleware. It does not apply to other controllers.
+The `middleware` array on a controller runs only for the direct actions in that controller, before action middleware. It does not apply to other controllers.
 
 ```typescript
 export default createController(routes.admin, {
@@ -338,22 +341,16 @@ router.post(routes.logout, logoutAction)
 
 ## Typed Context
 
-Define an `AppContext` type from your middleware stack, then make it the default context used by `createAction()` and `createController()`:
+Define an `AppContext` type from your router, then make it the default context used by `createAction()` and `createController()`:
 
 ```typescript
-import type { MiddlewareContext, ContextWithParams, AnyParams } from 'remix/router'
-
-type RootMiddleware = [
-  ReturnType<typeof formData>,
-  ReturnType<typeof session>,
-  ReturnType<typeof loadDatabase>,
-  ReturnType<typeof loadAuth>,
-]
-
-export type AppContext<params extends AnyParams = {}> = ContextWithParams<
-  MiddlewareContext<RootMiddleware>,
-  params
->
+import { createRouter, type RouterContext } from 'remix/router'
+
+export const router = createRouter({
+  middleware: [formData(), session(cookie, storage), loadDatabase(), loadAuth()],
+})
+
+export type AppContext = RouterContext<typeof router>
 
 declare module 'remix/router' {
   interface RouterTypes {