@exposify/next 0.0.0-stage → 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,196 @@
+import { ProposedField, LoginField, DocSource, RouteMarker, AgentReadyOptions } from '@exposify/core';
+export { HostedAuthResolverConfig, completeMcpLogin, createHostedAuthResolver, describe, exposed, hidden, hostedBroker } from '@exposify/core';
+import { A as ActionField } from './fields-olvyFnxj.cjs';
+
+interface AppRouteEntry {
+    router: "app";
+    /** `/api/orders/:id`; catch-alls as `:slug*`, optional ones as `:slug*?`. */
+    path: string;
+    params: string[];
+    /** Project-relative, for messages. */
+    file: string;
+    /** Exported methods when generated; the loaded module's exports win at runtime. */
+    methods: string[];
+    /** Loads the route module to read exposed()/hidden()/describe() off its exports. Absent for edge routes. */
+    load?: () => Promise<Record<string, unknown>>;
+    /** `export const runtime = "edge"`: not loaded into the Node MCP route, so markers there aren't read. */
+    edge?: boolean;
+}
+interface PagesRouteEntry {
+    router: "pages";
+    path: string;
+    params: string[];
+    file: string;
+}
+type ManifestRoute = AppRouteEntry | PagesRouteEntry;
+/** An exported function of a `"use server"` module. */
+interface ManifestAction {
+    /** Unique among actions: the default tool name, and the URL segment under `<mcpPath>/actions/`. */
+    key: string;
+    file: string;
+    export: string;
+    /** How each parameter is filled on a call, in order: see `ActionParamRole` in parse.ts. */
+    params: Array<{
+        name: string;
+        role: "formData" | "prev" | "input" | "object";
+    }>;
+    /** It sets or deletes a cookie, which would land on exposify's internal call rather than the agent's client. */
+    setsCookies?: boolean;
+    /** What it takes, worked out from its code (fields.ts): its tool schema when the app doesn't write one. */
+    fields: ActionField[];
+    /** It reads every form field, so its code doesn't say which exist. */
+    readsAll?: boolean;
+    /** What the analysis couldn't work out ("line N: …"): with any, the app writes the schema. */
+    unresolved?: string[];
+    /** The forms that submit to it (pass 3), where they are. */
+    forms?: Array<{
+        file: string;
+        line: number;
+    }>;
+    /** An input `describe` proposed and a person accepted, current with the code: used when `fields` can't be the schema. */
+    proposed?: ProposedField[];
+    /**
+     * A page that uses it (`/checkout`, `/admin/orders/:id`): tool calls are
+     * sent there as a real Server Action request. Absent when no page uses it;
+     * it's then called in-process by the MCP route.
+     */
+    host?: string;
+    /**
+     * The app's own checks it runs first (`lib/auth.ts#requireAdmin`): a
+     * user who doesn't pass one doesn't see the tool (guards.ts).
+     */
+    guards?: string[];
+    load: () => Promise<Record<string, unknown>>;
+}
+/** An App Router page: a read tool that fetches it like a browser (pages.ts). */
+interface ManifestPage {
+    /** Tool name, e.g. `view_product_slug`. */
+    name: string;
+    /** `/product/:slug`, as routes are written. */
+    path: string;
+    params: string[];
+    file: string;
+    /** Search params its code reads: optional tool arguments, sent as the query. */
+    search?: string[];
+    /** From its static `metadata`. */
+    title?: string;
+    description?: string;
+    /** Just a form posting to a Server Action: not a tool unless `pages` lists it. */
+    formOnly?: boolean;
+    /** The app's own checks it runs (`lib/auth.ts#requireAdmin`), see ManifestAction.guards. */
+    guards?: string[];
+}
+/**
+ * The app's own login (login.ts): a sign-in form under the MCP route makes
+ * this request, for Connect with no code. `host` is the page with the
+ * action's form, which tool calls redirected to mean "signed out".
+ */
+type ManifestLogin = {
+    kind: "action";
+    key: string;
+    fields: LoginField[];
+    host?: string;
+} | {
+    kind: "route";
+    path: string;
+    fields: LoginField[];
+    body: "json" | "form";
+};
+interface ExposifyManifest {
+    info: {
+        name: string;
+        version: string;
+    };
+    /** next.config's basePath, prefixed to every tool call's path. */
+    basePath?: string;
+    /** next.config's trailingSlash: tool calls add one, so they aren't redirected. */
+    trailingSlash?: boolean;
+    routes: ManifestRoute[];
+    /** The MCP route's URL without its catch-all segment, e.g. `/mcp`: Server Actions are served under `<mcpPath>/actions/`. */
+    mcpPath?: string;
+    actions?: ManifestAction[];
+    pages?: ManifestPage[];
+    login?: ManifestLogin;
+    /** Docs for search_docs, embedded so they work without a file system. */
+    docs: DocSource[];
+    /** exposify.descriptions.json's texts, "METHOD /path" -> text. */
+    descriptions?: Record<string, string>;
+}
+
+/** Set on every tool call; the MCP route refuses requests carrying it, so a tool can never call the MCP endpoint. */
+declare const DISPATCH_HEADER = "x-exposify-dispatch";
+type InputShape = NonNullable<Extract<RouteMarker, {
+    kind: "described";
+}>["input"]>;
+interface NextActionOptions {
+    /** Tool name. Default: the action's export name, snake_cased (`placeOrder` -> `place_order`). */
+    name?: string;
+    description?: string;
+    /**
+     * The action's input, as a zod shape: its form's field names (`true` is
+     * sent as a checked checkbox, "on"; arrays as repeated fields; objects as
+     * JSON), and the names of any parameters it takes before the FormData
+     * (`.bind` arguments). Required for any action that takes input.
+     */
+    input?: InputShape;
+}
+interface NextAiReadyOptions extends Omit<AgentReadyOptions, "docs"> {
+    /**
+     * Where tool calls are sent. Default: the origin the MCP request came in on
+     * (else the EXPOSIFY_BASE_URL environment variable). Set it when that
+     * origin isn't reachable from the server itself, e.g. behind a proxy that
+     * only the outside world can resolve.
+     */
+    baseUrl?: string;
+    /**
+     * The app's OpenAPI document (import the JSON): matching operations give
+     * tools input schemas and descriptions (below describe() and
+     * exposify.descriptions.json).
+     */
+    openapi?: object;
+    /**
+     * Server Actions to expose as tools, by export name (or by tool name when
+     * two files export the same name). Actions are writes, so none is exposed
+     * unless listed here or wrapped in exposed()/describe() in its module.
+     * `true` is enough for an action that takes no input.
+     */
+    actions?: Record<string, NextActionOptions | true>;
+    /**
+     * App Router pages are read tools by default: a call fetches the page like
+     * a browser (with the agent's credentials) and returns its main content as
+     * text, plus the data it was rendered with. `false` turns them off; by
+     * path (`"/product/:slug"`), `false` hides one, `true` brings back one
+     * that's just a form, and an object names or describes one. `exclude`
+     * globs apply to pages too.
+     */
+    pages?: false | Record<string, NextPageOptions | boolean>;
+    /**
+     * MCP requests allowed per client address per window (default 60 per
+     * 60 s). In-memory and per instance: best effort, as for the other web
+     * adapters; real limits belong to your platform's gateway.
+     */
+    rateLimit?: number;
+    rateWindowMs?: number;
+    /**
+     * The app's own login, for Connect with the hosted broker: AI assistants
+     * sign in on a form this route serves at `<MCP path>/login`, which makes
+     * this login request inside the app. Found by `withExposify` (a Server
+     * Action or a POST route that takes a password and sets a session). Name
+     * another Server Action (by export name), a route (`{ path, fields }`),
+     * or `false` to not offer it.
+     */
+    login?: false | string | {
+        path: string;
+        fields: string[];
+        body?: "json" | "form";
+    };
+}
+interface NextPageOptions {
+    /** Tool name. Default: `view_` and the path, snake_cased. */
+    name?: string;
+    description?: string;
+}
+type NextMcpHandler = (req: Request) => Promise<Response>;
+declare function aiReady(manifest: ExposifyManifest, options?: NextAiReadyOptions): NextMcpHandler;
+
+export { type AppRouteEntry, DISPATCH_HEADER, type ExposifyManifest, type ManifestAction, type ManifestLogin, type ManifestPage, type ManifestRoute, type NextActionOptions, type NextAiReadyOptions, type NextMcpHandler, type NextPageOptions, type PagesRouteEntry, aiReady };

package/dist/index.d.ts

@@ -0,0 +1,196 @@
+import { ProposedField, LoginField, DocSource, RouteMarker, AgentReadyOptions } from '@exposify/core';
+export { HostedAuthResolverConfig, completeMcpLogin, createHostedAuthResolver, describe, exposed, hidden, hostedBroker } from '@exposify/core';
+import { A as ActionField } from './fields-olvyFnxj.js';
+
+interface AppRouteEntry {
+    router: "app";
+    /** `/api/orders/:id`; catch-alls as `:slug*`, optional ones as `:slug*?`. */
+    path: string;
+    params: string[];
+    /** Project-relative, for messages. */
+    file: string;
+    /** Exported methods when generated; the loaded module's exports win at runtime. */
+    methods: string[];
+    /** Loads the route module to read exposed()/hidden()/describe() off its exports. Absent for edge routes. */
+    load?: () => Promise<Record<string, unknown>>;
+    /** `export const runtime = "edge"`: not loaded into the Node MCP route, so markers there aren't read. */
+    edge?: boolean;
+}
+interface PagesRouteEntry {
+    router: "pages";
+    path: string;
+    params: string[];
+    file: string;
+}
+type ManifestRoute = AppRouteEntry | PagesRouteEntry;
+/** An exported function of a `"use server"` module. */
+interface ManifestAction {
+    /** Unique among actions: the default tool name, and the URL segment under `<mcpPath>/actions/`. */
+    key: string;
+    file: string;
+    export: string;
+    /** How each parameter is filled on a call, in order: see `ActionParamRole` in parse.ts. */
+    params: Array<{
+        name: string;
+        role: "formData" | "prev" | "input" | "object";
+    }>;
+    /** It sets or deletes a cookie, which would land on exposify's internal call rather than the agent's client. */
+    setsCookies?: boolean;
+    /** What it takes, worked out from its code (fields.ts): its tool schema when the app doesn't write one. */
+    fields: ActionField[];
+    /** It reads every form field, so its code doesn't say which exist. */
+    readsAll?: boolean;
+    /** What the analysis couldn't work out ("line N: …"): with any, the app writes the schema. */
+    unresolved?: string[];
+    /** The forms that submit to it (pass 3), where they are. */
+    forms?: Array<{
+        file: string;
+        line: number;
+    }>;
+    /** An input `describe` proposed and a person accepted, current with the code: used when `fields` can't be the schema. */
+    proposed?: ProposedField[];
+    /**
+     * A page that uses it (`/checkout`, `/admin/orders/:id`): tool calls are
+     * sent there as a real Server Action request. Absent when no page uses it;
+     * it's then called in-process by the MCP route.
+     */
+    host?: string;
+    /**
+     * The app's own checks it runs first (`lib/auth.ts#requireAdmin`): a
+     * user who doesn't pass one doesn't see the tool (guards.ts).
+     */
+    guards?: string[];
+    load: () => Promise<Record<string, unknown>>;
+}
+/** An App Router page: a read tool that fetches it like a browser (pages.ts). */
+interface ManifestPage {
+    /** Tool name, e.g. `view_product_slug`. */
+    name: string;
+    /** `/product/:slug`, as routes are written. */
+    path: string;
+    params: string[];
+    file: string;
+    /** Search params its code reads: optional tool arguments, sent as the query. */
+    search?: string[];
+    /** From its static `metadata`. */
+    title?: string;
+    description?: string;
+    /** Just a form posting to a Server Action: not a tool unless `pages` lists it. */
+    formOnly?: boolean;
+    /** The app's own checks it runs (`lib/auth.ts#requireAdmin`), see ManifestAction.guards. */
+    guards?: string[];
+}
+/**
+ * The app's own login (login.ts): a sign-in form under the MCP route makes
+ * this request, for Connect with no code. `host` is the page with the
+ * action's form, which tool calls redirected to mean "signed out".
+ */
+type ManifestLogin = {
+    kind: "action";
+    key: string;
+    fields: LoginField[];
+    host?: string;
+} | {
+    kind: "route";
+    path: string;
+    fields: LoginField[];
+    body: "json" | "form";
+};
+interface ExposifyManifest {
+    info: {
+        name: string;
+        version: string;
+    };
+    /** next.config's basePath, prefixed to every tool call's path. */
+    basePath?: string;
+    /** next.config's trailingSlash: tool calls add one, so they aren't redirected. */
+    trailingSlash?: boolean;
+    routes: ManifestRoute[];
+    /** The MCP route's URL without its catch-all segment, e.g. `/mcp`: Server Actions are served under `<mcpPath>/actions/`. */
+    mcpPath?: string;
+    actions?: ManifestAction[];
+    pages?: ManifestPage[];
+    login?: ManifestLogin;
+    /** Docs for search_docs, embedded so they work without a file system. */
+    docs: DocSource[];
+    /** exposify.descriptions.json's texts, "METHOD /path" -> text. */
+    descriptions?: Record<string, string>;
+}
+
+/** Set on every tool call; the MCP route refuses requests carrying it, so a tool can never call the MCP endpoint. */
+declare const DISPATCH_HEADER = "x-exposify-dispatch";
+type InputShape = NonNullable<Extract<RouteMarker, {
+    kind: "described";
+}>["input"]>;
+interface NextActionOptions {
+    /** Tool name. Default: the action's export name, snake_cased (`placeOrder` -> `place_order`). */
+    name?: string;
+    description?: string;
+    /**
+     * The action's input, as a zod shape: its form's field names (`true` is
+     * sent as a checked checkbox, "on"; arrays as repeated fields; objects as
+     * JSON), and the names of any parameters it takes before the FormData
+     * (`.bind` arguments). Required for any action that takes input.
+     */
+    input?: InputShape;
+}
+interface NextAiReadyOptions extends Omit<AgentReadyOptions, "docs"> {
+    /**
+     * Where tool calls are sent. Default: the origin the MCP request came in on
+     * (else the EXPOSIFY_BASE_URL environment variable). Set it when that
+     * origin isn't reachable from the server itself, e.g. behind a proxy that
+     * only the outside world can resolve.
+     */
+    baseUrl?: string;
+    /**
+     * The app's OpenAPI document (import the JSON): matching operations give
+     * tools input schemas and descriptions (below describe() and
+     * exposify.descriptions.json).
+     */
+    openapi?: object;
+    /**
+     * Server Actions to expose as tools, by export name (or by tool name when
+     * two files export the same name). Actions are writes, so none is exposed
+     * unless listed here or wrapped in exposed()/describe() in its module.
+     * `true` is enough for an action that takes no input.
+     */
+    actions?: Record<string, NextActionOptions | true>;
+    /**
+     * App Router pages are read tools by default: a call fetches the page like
+     * a browser (with the agent's credentials) and returns its main content as
+     * text, plus the data it was rendered with. `false` turns them off; by
+     * path (`"/product/:slug"`), `false` hides one, `true` brings back one
+     * that's just a form, and an object names or describes one. `exclude`
+     * globs apply to pages too.
+     */
+    pages?: false | Record<string, NextPageOptions | boolean>;
+    /**
+     * MCP requests allowed per client address per window (default 60 per
+     * 60 s). In-memory and per instance: best effort, as for the other web
+     * adapters; real limits belong to your platform's gateway.
+     */
+    rateLimit?: number;
+    rateWindowMs?: number;
+    /**
+     * The app's own login, for Connect with the hosted broker: AI assistants
+     * sign in on a form this route serves at `<MCP path>/login`, which makes
+     * this login request inside the app. Found by `withExposify` (a Server
+     * Action or a POST route that takes a password and sets a session). Name
+     * another Server Action (by export name), a route (`{ path, fields }`),
+     * or `false` to not offer it.
+     */
+    login?: false | string | {
+        path: string;
+        fields: string[];
+        body?: "json" | "form";
+    };
+}
+interface NextPageOptions {
+    /** Tool name. Default: `view_` and the path, snake_cased. */
+    name?: string;
+    description?: string;
+}
+type NextMcpHandler = (req: Request) => Promise<Response>;
+declare function aiReady(manifest: ExposifyManifest, options?: NextAiReadyOptions): NextMcpHandler;
+
+export { type AppRouteEntry, DISPATCH_HEADER, type ExposifyManifest, type ManifestAction, type ManifestLogin, type ManifestPage, type ManifestRoute, type NextActionOptions, type NextAiReadyOptions, type NextMcpHandler, type NextPageOptions, type PagesRouteEntry, aiReady };