@exposify/next 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exposify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,329 @@
-# Temporary Holding Version
+# @exposify/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Next.js integration for [Exposify](../../README.md): your route handlers,
+pages and Server Actions become MCP tools that AI agents can call, at `/mcp` on
+your own app.
+
+```sh
+npm install @exposify/next
+npx exposify-next setup   # pick the endpoints, get the route file to create
+```
+
+Or by hand, in two files:
+
+```ts
+// next.config.ts
+import { withExposify } from "@exposify/next/config";
+
+export default withExposify(nextConfig);
+```
+
+```ts
+// app/mcp/[[...transport]]/route.ts
+import { aiReady } from "@exposify/next";
+import { exposify } from "../../../exposify.generated";
+
+const handler = aiReady(exposify, { expose: ["POST /api/orders"] });
+
+export { handler as GET, handler as POST, handler as DELETE };
+```
+
+`withExposify()` writes `exposify.generated.ts` whenever `next dev` or `next
+build` starts, and keeps it current in dev as route files change. It holds
+the route table, your Server Actions, your docs (`README.md`, `docs/**/*.md`) for `search_docs`,
+and `exposify.descriptions.json`'s texts, so nothing is read from disk at
+runtime. Commit it or ignore it; `npx exposify-next generate` writes it too.
+
+## Which routes become tools
+
+Every method an `app/**/route.ts` exports: reads (`GET`) are exposed by
+default, writes need an opt-in, as with every Exposify adapter.
+
+```ts
+import { describe, exposed, hidden } from "@exposify/next";
+import { z } from "zod";
+
+export async function GET() {}                    // exposed (a read)
+export const POST = exposed(async (req) => {});   // a write, opted in
+export const DELETE = hidden(async () => {});     // never a tool
+
+export const PATCH = describe(async (req) => {}, {
+  name: "update_order",
+  description: "Change an order's quantity",
+  input: { id: z.string(), body: z.object({ qty: z.number().int().min(1) }) },
+});
+```
+
+Or in config: `expose: ["POST /api/orders"]`, `exclude: ["/api/admin/**"]`.
+Paths are what Next serves: route groups like `(shop)` drop out, `[id]`
+becomes `:id`, `[...slug]` becomes `:slug*` and `[[...slug]]` becomes
+`:slug*?` (the tool takes `"a/b/c"`).
+
+**Pages Router** (`pages/api/*`): one handler serves every method, so nothing
+proves which methods exist. A Pages route becomes a tool only for the
+methods you list, reads included: `expose: ["GET /api/stats"]`. `setup`
+reads your handler (`if (req.method === …)`, `switch (req.method)`,
+next-connect's `.get()`/`.post()`) and suggests them.
+
+## How tool calls run
+
+A tool call is an HTTP request to your own app's origin, with the agent's
+`Authorization` and `Cookie` headers. So `proxy.ts` (middleware), and each
+route's own checks, run exactly as for a browser: a signed-out agent gets
+your 401, and a redirect to your login page comes back as an error naming
+it. The MCP client's address and host are forwarded as
+`x-forwarded-for`/`x-forwarded-host`.
+
+- `baseUrl` (or `EXPOSIFY_BASE_URL`): where tool calls go, when the request's
+  own origin isn't reachable from the server.
+- **Vercel Deployment Protection** blocks those requests on protected
+  previews: set `VERCEL_AUTOMATION_BYPASS_SECRET` (Vercel's "Protection
+  Bypass for Automation") and it's sent as `x-vercel-protection-bypass`.
+- `basePath` and `trailingSlash` from `next.config` are applied.
+- `rateLimit` / `rateWindowMs`: MCP requests per client address per window
+  (default 60 per 60 s), in memory and per instance.
+- `oauth`, `auth`, `docsAuth` and `openapi` work as in `@exposify/express`.
+  With `oauth`, the protected-resource metadata is served at
+  `/mcp/.well-known/oauth-protected-resource`.
+
+The MCP route runs on the Node.js runtime. Routes with `export const runtime
+= "edge"` are tools too, but their `exposed()`/`describe()` wrappers aren't
+read (their modules aren't loaded into the Node route): use `expose`/`exclude`
+for those.
+
+## Each user sees the tools they can use
+
+Tools behind your own checks are listed only for people who pass them. The
+generator notes which of your functions a page or Server Action calls that
+stop a request with `notFound()`, `redirect()`, `forbidden()` or
+`unauthorized()` (say `requireAdmin()` and `requireUser()`), directly or
+through another one. When an agent lists tools, the MCP route opens one page
+per check as that agent's user (a page without params that runs it), and
+leaves out every tool behind a check they don't pass. So a customer's
+assistant doesn't see `view_admin` or `save_product`; an admin's does.
+
+- One request per check per user, cached for a minute.
+- A check with no page to try it on, or a probe that errors, leaves its
+  tools listed. Your checks still run on every call either way: this only
+  changes what's listed.
+- Checks written inline in a page (`if (!user) redirect("/login")`) aren't
+  shared functions, so those pages stay listed.
+
+## AI assistants sign in with your own login
+
+With `EXPOSIFY_KEY` set (the hosted broker), an AI assistant that connects
+signs in with your app's own login, and you write no code for it:
+
+1. The generator finds your login: a Server Action (or a `POST` route
+   handler) that takes a password and something saying who, and sets a
+   session cookie or returns a token. Sign-up, sign-out and password-reset
+   actions are never picked.
+2. When Claude connects, the person clicks Allow on Exposify's page and lands
+   on a sign-in form this MCP route serves at `/mcp/login`, on your domain.
+   The password goes to your app only.
+3. The form runs your login exactly as your own form does (a real Server
+   Action on the page that uses it), with no browser cookies, so it's a
+   session of its own. Its cookies go to the broker for this connection, and
+   every tool call after that runs as that person.
+4. Cookies your app sets on later calls are kept. A 401, or a redirect to
+   your login page, ends the connection, and the assistant asks to connect
+   again.
+
+The MCP route tells Exposify about the login (its field names) and its
+address before answering its first request, so there's nothing to add in
+the dashboard; it shows there with an off switch. `inspect` says which login
+was found. Name another one with `aiReady(exposify, { login: "signIn" })`
+(an action's export name) or `{ login: { path: "/api/login", fields:
+["email", "password"] } }`, or turn it off with `login: false`.
+
+**No login found, and no sign-in method in the dashboard?** Then agents use
+your app signed out: `/mcp` doesn't ask them to sign in, and your own checks
+decide what they can do. The startup log says which it is
+(`[agentready] How agents sign in: ...`), and so does the dashboard's "How
+agents sign in" page. Adding a sign-in method there takes effect within a
+minute.
+
+Not supported yet: logins in more than one step (SMS codes, email links),
+and logins that need a CSRF token from your own form page.
+
+## Pages
+
+Every App Router page is a read tool too, so an app whose server components
+read their data directly (a database client, an ORM, `fetch`, `"use cache"`
+functions), with no API route in between, is readable by agents with no code
+changes. `/shop/[category]` becomes `view_shop_category { category }`, `/`
+becomes `view_home`.
+
+A call requests the page the way a browser does, with the agent's
+`Authorization` and `Cookie`, so your own checks run: `proxy.ts`, a login
+check in a layout or the page, `notFound()`, `redirect()`. It returns:
+
+```json
+{ "url": "/product/celeste", "title": "Celeste | Shop", "text": "# Celeste\n\n$348.00\n…", "data": [{ "component": "AddToCart", "props": { "product": { … } } }] }
+```
+
+- `text` is the page's main content (`<main>`, or the body without its
+  header, nav, footer and aside) as compact text: headings, lists, tables,
+  links (a card wrapped in a link ends with `→ /its/url`), images' alt text
+  and form controls. Scripts, styles and hidden elements are left out.
+- `data` is what the page was rendered with: the props your server
+  components pass to client components, read from the payload Next already
+  puts in the page. A page that renders its list in server components only
+  has no such props, and its `text` carries the list.
+- A `redirect()` or `notFound()` comes back as the error a route's would
+  (`redirected to /login`, a 404), also when the page streams and Next has
+  already answered 200 (Suspense, `cacheComponents`).
+- Each `[param]` is an argument; a catch-all takes `"a/b/c"`. Search params
+  the page reads (`searchParams.q`, `(await searchParams).page`, a
+  destructure, `useSearchParams().get("tab")` in a client component it
+  renders) are optional arguments.
+- The description is the page's static `metadata` (`description`, else
+  `title`), the descriptions file (`GET /path`, which `describe` writes), or
+  a derived one.
+
+What's left out, and how to change it:
+
+- A page that's **just a form** posting to a Server Action (a sign-in page,
+  say) isn't a tool: the action is. List `"GET /login"` in `expose` (setup's
+  checklist does) to read it anyway.
+- `exclude` globs apply to pages, as to routes: `exclude: ["/admin/**"]`.
+- `pages: false` turns page tools off. By path, `false` hides one and an
+  object renames or describes one:
+  `pages: { "/": { name: "storefront", description: "…" }, "/debug": false }`.
+
+Data a page fetches in the browser after it loads (`useEffect`, SWR) isn't in
+its HTML, so its tool doesn't see it. A page tool is a full render: cheap for
+cached pages, a normal request otherwise.
+
+## Server Actions
+
+The exported functions of every `"use server"` file are listed in the
+generated manifest, with the input each one takes, worked out from its code:
+the fields it reads off its FormData (`formData.get("email")`, through
+same-file helpers like `field("email")` or `parseProduct(formData)`, and
+names built over a constant list, like `` `stock_${size}` `` for each of
+`SIZES`), and their types (`Number(…)` is a number, `=== "on"` a checkbox,
+`JSON.parse(…)` JSON, `STATUSES.includes(…)` one of `STATUSES`). Constant
+lists are followed into the files they're imported from, through your
+tsconfig `paths`.
+
+Then the forms that submit to each action (`<form action={…}>`,
+`onSubmit={…}` around it, `<button formAction={…}>`, through
+`useActionState` or `.bind(null, id)`, or an inline wrapper that calls it)
+add what only the form says: which fields are `required`, `min`/`max`,
+`minLength`/`maxLength`, `pattern`, `<select>` and radio options, and which
+of the action's parameters are `.bind` arguments or `useActionState`'s
+previous state. Wrapper components (`<Field name="email" />` rendering
+`<input required {...props} />`) are followed to the input they render. A
+field required by every form that has it is required in the tool; hidden
+inputs count as required unless they're rendered conditionally.
+
+Actions are writes, so none is a tool until you opt it in:
+
+```ts
+// app/mcp/[[...transport]]/route.ts
+const handler = aiReady(exposify, {
+  actions: {
+    placeOrder: { description: "Place an order" }, // input worked out from its code
+    // Or written out, which wins: form field names, and a parameter before the FormData (a `.bind` argument) by its name.
+    updateOrderStatus: { input: { orderId: z.string(), status: z.enum(["paid", "shipped"]) } },
+    clearCart: true,
+  },
+});
+```
+
+Actions fill in defaults for missing fields instead of rejecting them, so a
+wrong schema would let an agent save wrong data. An action whose input
+can't all be worked out stays hidden, with a warning naming what (a field
+name computed at runtime, the form handed to a function from a package, a
+parameter with no type), until you write its `input`; so does one that reads
+the whole form (`Object.fromEntries(formData)`) with no form found to say
+which fields it gets, and one that takes a file, which agents can't send
+yet. Fields no form requires are optional; the tool's description tells the
+agent a field left out is as if left blank.
+
+Or in the action's own file: `export const clearCart = describe(async () => { … }, { description: "…" })`
+(`exposed()` and `hidden()` work too). Tools are named after the export,
+snake_cased (`place_order`), with the file's name added where two files
+export the same name.
+
+A call is sent to your app the way a browser's form sends it: a Server Action
+request (`Next-Action`) to a page that uses the action, which the code
+generator finds by following imports from your pages and layouts. Next runs
+it as a real Server Action, so everything works as for a browser:
+`updateTag()`, `refresh()`, `revalidatePath()`, `redirect()`, and
+`cookies()`/`headers()`, which are the agent's. Nothing in your code changes,
+and nothing needs configuring. An action no page uses has no such page: the
+MCP route (it must be the `[[...transport]]` catch-all) calls it in-process
+at `/mcp/actions/<tool>` instead, where Next treats it as part of a route
+handler and refuses `updateTag()` and `refresh()`; the startup log names
+those actions. Arguments become the FormData a browser would post: `true` is a
+checked checkbox (`"on"`), `false` is left out, arrays are repeated fields,
+objects are JSON, and a field the action `JSON.parse`s is sent whole as JSON. A useActionState action's previous state is `undefined`.
+The result is the action's return value as JSON; a `redirect()` comes back
+as `{ ok: true, redirectedTo }`, since for an action it's usually success
+(saved, then off to the list page). `notFound()` and thrown errors are tool
+errors; the thrown message stays in your server log.
+
+- **Check auth inside each action.** A call goes to one page that uses the
+  action, and Next's own guidance already says actions must check auth
+  themselves rather than rely on `proxy.ts` rules for the page.
+- **Sign-in actions don't work for agents.** A cookie an action sets lands on
+  the internal call, not the agent's client. Actions that call
+  `cookies().set`/`.delete`, or are named like `login`/`logout`/`register`,
+  get a warning if you opt them in.
+- **Next checks each call as it checks a browser's**, Origin against the
+  forwarded host. The in-process fallback skips that, so `/mcp/actions/*`
+  requires a secret header. In development it's random per process; in
+  production, an action no page uses needs `EXPOSIFY_ACTION_SECRET` (or
+  `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY`, which it's derived from) set to the
+  same value on every instance, since the instance serving a tool call may
+  not be the one that sent it. Without either, those actions are off in
+  production and the log says so. Actions a page uses need neither.
+- `"use server"` functions written inline in a component close over values
+  from the render, so they can't be called on their own; they're never
+  exposed.
+
+## CLI
+
+`npx exposify-next setup | inspect | describe | generate`. The first three
+are the same as `exposify-express`'s; the scan reads your route files
+instead of booting the app.
+
+Server Actions get their own rows:
+
+- `inspect` lists each action with whether it's a tool and why, its status
+  (input known, input partly unknown, or flagged as sign-in/out or taking a
+  file), the forms that submit to it, and what the scan couldn't tell. Where
+  an input you wrote no longer matches the code (a field the action now
+  reads, an option the form dropped), it says so, and `inspect --check` fails
+  on it in CI. The `inspect --snapshot` file includes action tools, by their
+  `POST /mcp/actions/<tool>` URL.
+- `setup`'s checklist lists actions after the routes: space picks each one,
+  and `a`/`!` (all routes, `expose: "*"`) leave them alone. Without a
+  terminal, use `--action placeOrder`. It prints their `actions` entries: `true`
+  when the scan knows the input, otherwise a zod stub with a
+  `// TODO(exposify):` line for each gap. Entries already in your config are
+  kept as you wrote them.
+- After a `next build`, actions that Next knows but the scan didn't find
+  (re-exported from elsewhere, say) are listed.
+- `describe` writes descriptions for exposed actions too, into
+  `exposify.descriptions.json` under each action's tool URL (`POST
+  /mcp/actions/place_order`). A `description` in config or `describe()` wins.
+- For an action you've opted in whose input the scan can't complete,
+  `describe` can ask the description service to propose one from the action's
+  source and its forms' source. It first lists every file whose code would be
+  sent (form files go whole) and sends only if you answer `y`; with
+  `--no-source` it sends names and fields only. You see each proposed field, and anything it
+  still couldn't tell, then accept or skip it. An accepted input goes in
+  `exposify.descriptions.json`, and the MCP route uses it once
+  `exposify.generated.ts` is regenerated. If the action changes, the input is
+  stale and unused until reviewed again: the startup log and `describe
+  --check` say so. A written `input` always wins, and actions that take a
+  file stay hidden either way.
+- Inline `"use server"` functions get a suggested change from `setup`: a new
+  `actions.ts` next to the page with the function exported. The values it
+  closed over become its first parameters, and the page passes them with
+  `.bind(null, …)`. A `TODO(exposify)` reminds you to check the caller may act
+  on them, since the closure was often the authorisation. It's printed,
+  never applied.

package/dist/chunk-D5TQF5DY.js

@@ -0,0 +1,53 @@
+// src/routes.ts
+var HTTP_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+var DEFAULT_PAGE_EXTENSIONS = ["tsx", "ts", "jsx", "js"];
+function appRoute(dirSegments) {
+  const parts = [];
+  const params = [];
+  for (const seg of dirSegments) {
+    if (seg.startsWith("_") || seg.startsWith("@") || seg.startsWith("(.")) return null;
+    if (seg.startsWith("(") && seg.endsWith(")")) continue;
+    const part = dynamicSegment(seg, params);
+    if (part === null) return null;
+    parts.push(part);
+  }
+  return { path: `/${parts.join("/")}`, params };
+}
+function pagesApiRoute(segments) {
+  if (segments[0] !== "api") return null;
+  const segs = segments.at(-1) === "index" ? segments.slice(0, -1) : segments;
+  const parts = [];
+  const params = [];
+  for (const seg of segs) {
+    if (seg.startsWith("_")) return null;
+    const part = dynamicSegment(seg, params);
+    if (part === null) return null;
+    parts.push(part);
+  }
+  return { path: `/${parts.join("/")}`, params };
+}
+function dynamicSegment(seg, params) {
+  const optionalCatchAll = /^\[\[\.\.\.([A-Za-z0-9_]+)\]\]$/.exec(seg);
+  if (optionalCatchAll) {
+    params.push(optionalCatchAll[1]);
+    return `:${optionalCatchAll[1]}*?`;
+  }
+  const catchAll = /^\[\.\.\.([A-Za-z0-9_]+)\]$/.exec(seg);
+  if (catchAll) {
+    params.push(catchAll[1]);
+    return `:${catchAll[1]}*`;
+  }
+  const dynamic = /^\[([A-Za-z0-9_]+)\]$/.exec(seg);
+  if (dynamic) {
+    params.push(dynamic[1]);
+    return `:${dynamic[1]}`;
+  }
+  return seg.includes("[") ? null : seg;
+}
+
+export {
+  HTTP_METHODS,
+  DEFAULT_PAGE_EXTENSIONS,
+  appRoute,
+  pagesApiRoute
+};