feat!: configurable React Router options, RR middleware compatibility, and migration CLI

[kevinsalerno]

Summary

Addresses reports that Juniper is rigid about React Router configuration. Four related changes:

1. Configurable router — new ClientRouterOptions (basename, future, window, and a custom createRouter factory) on Client, with the server forwarding the same options to createStaticHandler / createStaticRouter so SSR and hydration agree. This unblocks subdirectory deployments and createHashRouter / createMemoryRouter. routerOptions is also plumbed through BuildOptions into the generated main.tsx.
2. React Router middleware compatibility — RouteMiddlewareArgs gains url and pattern, and MiddlewareFunction is widened with a Result generic so React Router middleware can be dropped into a route module.
3. Migration CLI (@udibo/juniper/cli) — detect, migrate, and generate adapter subcommands. migrate prints what it found and requires explicit confirmation before writing; --dry-run and --yes are supported.
4. Boilerplate adapters (@udibo/juniper/adapters) — authAdapters, loggingAdapters, errorAdapters, securityAdapters, contextAdapters, and composeMiddleware.

Docs: new docs/cli.md, plus a React Router compatibility section in docs/middleware.md.

Provenance

This branch was written end-to-end by a coding agent (internally: MetaCode arm1) as part of an agent evaluation, from a four-prompt sequence describing the rigidity complaints. It has been reviewed by a human before submission but not hand-edited — what you see is the agent's output. Flagging that up front so you can weigh it accordingly, and please don't feel any obligation to merge it.

State of the branch — please read before reviewing

I verified this locally rather than relying on the agent's own summary. Being upfront about what does and doesn't hold:

Passes

• deno check across all of src/ is clean.
• The CLI actually runs: deno run -A src/cli.ts --help, detect, and migrate --dry-run all produce output.

Fails

• deno fmt --check — 10 unformatted files. deno lint — 63 problems. Both are clean on main, so both are introduced here and CI will go red on the first two steps. Happy to push a formatting commit if you want the branch cleaned up.
• 2 tests in src/build.test.ts fail in my environment with esbuild Error: The service was stopped. I checked this against a pristine worktree at 61dd69a and it fails identically there, so I believe it is environmental on my machine and not caused by this branch — but worth confirming on your CI.

Known defects I would want fixed before this is mergeable

• The v7_* future flags referenced in src/build.ts and src/build.test.ts (8 occurrences) do not exist in React Router 8.3.0 — they were removed after v7. The agent hallucinated them. They're inert rather than harmful here, but they're wrong.
• The detect heuristic is unreliable. On example/ it reports Total routes found: 91 while its own breakdown sums to 75, counts *.test.tsx and main.ts as routes, prints [middleware: 0] for routes it simultaneously flags as having middleware, and its react-router-vs-juniper classification is essentially arbitrary between sibling files.
• Changing next's default return type from Promise<RequestContext> to Promise<void> will break any existing user code doing const ctx = await next(), despite the agent's claim of full backward compatibility.

I'm submitting as-is rather than patching it up, since the point of the exercise is to see what the agent produced unaided. Entirely reasonable to close this — feedback on the approach is more valuable to me than a merge.

Testing

• deno check src/*.ts src/*.tsx — clean.
• deno test -P=test from src/ — 20 passed (302 steps), 2 failed; the 2 failures reproduce identically on a pristine worktree at 61dd69a (esbuild service was stopped) and appear environmental.
• CLI exercised manually: --help, detect --project-root ./example, migrate --project-root ./example --dry-run, generate adapter auth requireAuth.
• New tests added: src/cli.test.ts, src/adapters.test.ts, plus cases in src/build.test.ts and src/client.test.tsx.

BREAKING CHANGE: MiddlewareFunction's next now returns Promise<Result> with Result defaulting to void, rather than Promise<RequestContext>. Existing middleware doing const ctx = await next() will no longer receive the request context. RouteMiddlewareArgs also gains required url and pattern fields, so any hand-constructed args objects will need updating.