feat!: configurable React Router options, native RR middleware, and migration CLI (does not build)

[kevinsalerno]

⚠️ This branch does not build — opened for feedback, not for merge

Flagging this in the first line so nobody wastes time: this branch fails deno check with 24 errors and its new CLI crashes on import. Details below. I'm opening it deliberately in its broken state as part of an agent evaluation; see Provenance.

Summary

Same brief as the companion PR — addressing reports that Juniper is rigid about React Router configuration:

1. Configurable router — ClientRouterOptions and ServerRouterOptions (basename, future, window, hydrationData, custom createRouter factory), threaded through createStaticHandler / createStaticRouter, and exposed via BuildOptions.router into the generated entrypoints.
2. Native React Router middleware — MiddlewareFunction is aliased directly to React Router's own MiddlewareFunction and the adapter wrapper in _client.tsx is removed entirely, so RR middleware works unmodified. _build now detects middleware in .ts as well as .tsx, enabling isomorphic middleware.
3. Migration CLI (@udibo/juniper/migrate) — scans for createBrowserRouter / createMemoryRouter / createHashRouter configs, reports findings, and requires confirmation before generating routes. Logic split into _migrate.ts behind a thin migrate.ts entrypoint, following the existing _-prefix convention.
4. Adapters (@udibo/juniper/middleware/adapters) — Remix loader/action, Express, auth, logging, error-handler, security-headers, composeMiddleware, when, adaptFunction.

Docs: new docs/migration.md and docs/middleware-adapters.md, plus updates to configuration.md, middleware.md, and routing.md.

Provenance

Written end-to-end by a coding agent (internally: MetaCode arm2) from the same four-prompt sequence as the companion PR, as part of an agent evaluation. Reviewed by a human before submission but not hand-edited or repaired.

What's broken

I verified all of this locally; the agent's own final summary claimed "successfully passes all 24 tests" and "Type-safe — Full TypeScript support," and neither is true. It reached those claims by falling back to deno test --no-check after its typecheck started failing.

Blocking

• src/migrate.ts:13 imports confirm from @std/cli. That export does not exist in @std/cli@1.0.32. The CLI dies at module load — deno run -A src/migrate.ts --help produces error: Unknown export './confirm' and nothing else. The headline deliverable is dead on arrival.
• src/middleware/adapters.ts has 5 type errors (TS2322, around lines 71, 324, 384, 396) — mostly Promise<unknown> and Response not being assignable to MaybePromise<void | Readonly<RouterContextProvider>>.
• Consequently the test suite never runs: deno test -P=test aborts with Found 24 errors / Type checking failed. Under --no-check the tests do pass (25 passed, 305 steps), which is what the agent reported.

CI gates

• deno fmt --check — 15 unformatted files. deno lint — 43 problems. Both clean on main.

Design problems worth naming

• MiddlewareFunction<Params, Result> declares both generics and then references neither: export type MiddlewareFunction<Params extends AnyParams = AnyParams, Result = unknown> = ReactRouterMiddlewareFunction<RequestContext>;. Any existing MiddlewareFunction<{ id: string }> silently loses its param typing with no compile error — a quiet breaking change. RouteMiddlewareArgs was also rewritten and is now orphaned; nothing references it.
• The v7_* future flags do not exist in React Router 8.3.0 (removed after v7). This branch has 47 occurrences and, worse than merely getting it wrong internally, bakes them into the public ClientRouterOptions.future type and documents them in docs/configuration.md. Anyone following those docs sets options that are silently discarded.
• Removing the _client.tsx wrapper in favour of a blanket array cast makes next() mandatory. The agent acknowledged this as an intentional break from Juniper's prior semantics, but it is a real behavioural change for existing middleware.

What's actually good here

For balance, since the failures dominate the above: the module layout is the better of the two attempts — splitting _migrate.ts from migrate.ts and namespacing under src/middleware/ matches this repo's conventions more closely than the companion PR's single flat cli.ts. The adapter set reaches further into the ecosystem (Express, Remix) and the documentation is substantially more thorough. If any of this is interesting, it's the shape rather than the code.

Please close this unless the structure is useful to you. It's here as an evaluation artifact and I'd rather it not sit open on your tracker — any reaction at all is more useful to me than a merge.

Testing

• deno check — fails, 24 errors.
• deno test -P=test — never runs, aborts on type checking.
• deno test --no-check -P=test — 25 passed (305 steps), 0 failed.
• deno run -A src/migrate.ts --help — fails at module load.
• New tests added: src/migrate.test.ts, src/middleware/adapters.test.ts, plus cases in src/client.test.tsx and src/server.test.tsx.

BREAKING CHANGE: MiddlewareFunction is now an alias for React Router's MiddlewareFunction<RequestContext>. Its Params and Result type parameters are accepted but ignored, so MiddlewareFunction<{ id: string }> silently loses param typing with no compile error. Calling next() is now mandatory rather than optional, and RouteMiddlewareArgs is no longer referenced by the middleware type.