@exposify/express 0.0.0

package/dist/index.cjs

@@ -0,0 +1,380 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  aiReady: () => aiReady,
+  describe: () => import_core3.describe,
+  exposed: () => import_core3.exposed,
+  hidden: () => import_core3.hidden,
+  routesFromExpress: () => routesFromExpress
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_path2 = require("path");
+var import_core2 = require("@exposify/core");
+var import_node2 = require("@exposify/core/node");
+
+// src/surface.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_light_my_request = require("light-my-request");
+var import_node = require("@exposify/core/node");
+
+// src/introspect.ts
+var import_core = require("@exposify/core");
+
+// src/mount-registry.ts
+var import_node_module = require("module");
+var import_meta = {};
+var recordedMounts = /* @__PURE__ */ new WeakMap();
+var patchedTargets = /* @__PURE__ */ new WeakSet();
+function installMountRecorder(routerCtor) {
+  try {
+    const RouterCtor = routerCtor ?? resolveExpressRouter();
+    if (typeof RouterCtor !== "function") return;
+    const target = resolvePatchTarget(RouterCtor);
+    if (!target) return;
+    if (patchedTargets.has(target)) return;
+    patchedTargets.add(target);
+    const original = target.use;
+    if (typeof original !== "function") return;
+    const originalUse = original;
+    const wrapper = function(...args) {
+      try {
+        recordUse(this, args);
+      } catch {
+      }
+      return originalUse.apply(this, args);
+    };
+    Object.defineProperty(wrapper, "name", { value: "use" });
+    target.use = wrapper;
+  } catch {
+  }
+}
+function getRecordedMounts(handle) {
+  if (typeof handle !== "function") return void 0;
+  return recordedMounts.get(handle);
+}
+function resolveExpressRouter() {
+  const req = resolveRequireFn();
+  if (!req) return void 0;
+  const expressModule = req("express");
+  return expressModule.Router;
+}
+function resolveRequireFn() {
+  try {
+    if (typeof require === "function" && typeof require.resolve === "function") return require;
+    return (0, import_node_module.createRequire)(import_meta.url);
+  } catch {
+    return void 0;
+  }
+}
+function resolvePatchTarget(RouterCtor) {
+  const proto = RouterCtor.prototype;
+  if (proto && typeof proto.use === "function") {
+    return proto;
+  }
+  if (typeof RouterCtor.use === "function") {
+    return RouterCtor;
+  }
+  return void 0;
+}
+function classifyFirstArg(first) {
+  let arg = first;
+  while (Array.isArray(arg) && arg.length !== 0) arg = arg[0];
+  if (typeof arg === "function") {
+    return { paths: ["/"], handlerOffset: 0 };
+  }
+  if (typeof first === "string") {
+    return { paths: [first], handlerOffset: 1 };
+  }
+  if (Array.isArray(first) && first.every((p) => typeof p === "string")) {
+    return { paths: first, handlerOffset: 1 };
+  }
+  return { paths: null, handlerOffset: 1 };
+}
+function recordUse(parent, args) {
+  if (args.length === 0) return;
+  const { paths, handlerOffset } = classifyFirstArg(args[0]);
+  if (paths === null) return;
+  const rawHandlers = args.slice(handlerOffset);
+  for (const fn of flattenHandlers(rawHandlers)) {
+    if (typeof fn !== "function") continue;
+    if (!Array.isArray(fn.stack)) continue;
+    const existing = recordedMounts.get(fn) ?? [];
+    for (const p of paths) {
+      if (!existing.some((e) => e.parent === parent && e.path === p)) {
+        existing.push({ parent, path: p });
+      }
+    }
+    recordedMounts.set(fn, existing);
+  }
+}
+function flattenHandlers(items) {
+  return items.flatMap((item) => Array.isArray(item) ? flattenHandlers(item) : [item]);
+}
+
+// src/introspect.ts
+function routesFromExpress(app, opts) {
+  const router = routerOf(app);
+  const out = [];
+  const walked = /* @__PURE__ */ new Map();
+  const unresolved = /* @__PURE__ */ new Set();
+  if (router?.stack) {
+    walk(router.stack, "", router, out, walked, unresolved);
+  }
+  if (opts?.mounts) {
+    for (const [prefix, handle] of Object.entries(opts.mounts)) {
+      try {
+        const resolved = ownerAndStackOf(handle);
+        if (!resolved) continue;
+        unresolved.delete(handle);
+        walkOnce(handle, prefix, resolved.stack, resolved.owner, out, walked, unresolved);
+      } catch {
+      }
+    }
+  }
+  if (unresolved.size > 0) warnMountSkipped();
+  return out;
+}
+var warnedAboutSkippedMount = false;
+function warnMountSkipped() {
+  if (warnedAboutSkippedMount) return;
+  warnedAboutSkippedMount = true;
+  try {
+    console.warn(
+      `[agentready] skipped one or more mounted routers: their mount path could not be determined automatically, so routes under them will not be exposed as tools. If aiReady() is registered before they're mounted, this is usually automatic (Express 5's mount recorder); otherwise pass them explicitly via aiReady({ mounts: { "/path": router } }).`
+    );
+  } catch {
+  }
+}
+function routerOf(app) {
+  if (!app || typeof app !== "object" && typeof app !== "function") return void 0;
+  const withRouter = app;
+  if (withRouter._router?.stack) return withRouter._router;
+  try {
+    return withRouter.router;
+  } catch {
+    return void 0;
+  }
+}
+function walk(stack, prefix, owner, out, walked, unresolved) {
+  for (const layer of stack) {
+    try {
+      if (layer.route) {
+        const path = joinPaths(prefix, layer.route.path);
+        const handlers = layer.route.stack.map((s) => s.handle);
+        const marker = handlers.map(import_core.getMarker).find(Boolean);
+        for (const [method, enabled] of Object.entries(layer.route.methods)) {
+          if (!enabled || method === "_all") continue;
+          out.push({
+            method: method.toUpperCase(),
+            path,
+            params: extractParams(path),
+            marker,
+            description: marker?.kind === "described" ? marker.description : void 0
+          });
+        }
+        continue;
+      }
+      const handle = layer.handle;
+      if (handle === void 0 || handle === null) continue;
+      const mountPaths = /* @__PURE__ */ new Set();
+      const recorded = getRecordedMountPaths(handle, owner);
+      if (recorded) for (const p of recorded) mountPaths.add(p);
+      const regexpMount = mountPathOf(layer);
+      if (regexpMount !== null) mountPaths.add(regexpMount);
+      const subAppMount = subAppMountOf(handle);
+      if (subAppMount !== null) mountPaths.add(subAppMount);
+      const resolved = mountPaths.size > 0 && walkEachVia([...mountPaths], handle, prefix, out, walked, unresolved);
+      if (resolved) continue;
+      if (looksRouterish(handle) || looksLikeExpressApp(handle)) {
+        unresolved.add(handle);
+      }
+    } catch {
+    }
+  }
+}
+function getRecordedMountPaths(handle, owner) {
+  const recorded = getRecordedMounts(handle);
+  if (!recorded) return null;
+  const paths = recorded.filter((entry) => entry.parent === owner).map((entry) => entry.path);
+  return paths.length > 0 ? paths : null;
+}
+function walkEachVia(mounts, handle, prefix, out, walked, unresolved) {
+  const resolved = ownerAndStackOf(handle);
+  if (!resolved) return false;
+  unresolved.delete(handle);
+  for (const mount of mounts) {
+    walkOnce(handle, joinPaths(prefix, mount), resolved.stack, resolved.owner, out, walked, unresolved);
+  }
+  return true;
+}
+function walkOnce(handle, prefix, stack, owner, out, walked, unresolved) {
+  let prefixes = walked.get(handle);
+  if (prefixes?.has(prefix)) return;
+  if (!prefixes) {
+    prefixes = /* @__PURE__ */ new Set();
+    walked.set(handle, prefixes);
+  }
+  prefixes.add(prefix);
+  walk(stack, prefix, owner, out, walked, unresolved);
+}
+function mountPathOf(layer) {
+  if (layer.regexp?.fast_slash) return "";
+  const source = layer.regexp?.source;
+  if (!source) return null;
+  const match = /^\^((?:\\\/[A-Za-z0-9._~-]+)+)\\\/\?(?:\(\?=\\\/\|\$\)|\$)/.exec(source);
+  if (!match) return null;
+  return match[1].replace(/\\\//g, "/");
+}
+function joinPaths(a, b) {
+  const joined = `${a}${b.startsWith("/") ? b : `/${b}`}`;
+  return joined.replace(/\/+/g, "/").replace(/(.)\/$/, "$1") || "/";
+}
+function extractParams(path) {
+  return [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((m) => m[1]);
+}
+function looksRouterish(handle) {
+  return Array.isArray(handle?.stack);
+}
+function looksLikeExpressApp(handle) {
+  if (typeof handle !== "function") return false;
+  const h = handle;
+  return typeof h.handle === "function" && typeof h.set === "function";
+}
+function subAppMountOf(handle) {
+  if (!looksLikeExpressApp(handle)) return null;
+  const mountpath = handle.mountpath;
+  const value = Array.isArray(mountpath) ? mountpath[0] : mountpath;
+  if (typeof value !== "string" || value === "/") return null;
+  return value;
+}
+function ownerAndStackOf(handle) {
+  const direct = handle?.stack;
+  if (Array.isArray(direct)) return { owner: handle, stack: direct };
+  const sub = routerOf(handle);
+  if (sub?.stack) return { owner: sub, stack: sub.stack };
+  return void 0;
+}
+
+// src/surface.ts
+async function buildExpressSurface(app, cfg, cwd, opts) {
+  const info = await readPackageInfo(cwd);
+  const appish = app;
+  if (!appish.request || !appish.response) {
+    console.warn(
+      "[agentready] express request/response prototypes not found; light-my-request corruption guard inactive"
+    );
+  }
+  const reqProto = appish.request ? Object.getPrototypeOf(appish.request) : void 0;
+  const resProto = appish.response ? Object.getPrototypeOf(appish.response) : void 0;
+  const pristineReqProto = reqProto ? Object.getPrototypeOf(reqProto) : void 0;
+  const pristineResProto = resProto ? Object.getPrototypeOf(resProto) : void 0;
+  return {
+    info,
+    routes: routesFromExpress(app, opts),
+    docs: await (0, import_node.loadDocsFromFs)(cfg.docs, cwd),
+    async dispatch(req) {
+      const url = new URL(req.url);
+      try {
+        const res = await (0, import_light_my_request.inject)(app, {
+          method: req.method,
+          url: url.pathname + url.search,
+          headers: Object.fromEntries(req.headers.entries()),
+          payload: req.body ? await req.text() : void 0
+        });
+        return new Response(res.body, {
+          status: res.statusCode,
+          headers: res.headers
+        });
+      } finally {
+        if (pristineReqProto && reqProto) Object.setPrototypeOf(reqProto, pristineReqProto);
+        if (pristineResProto && resProto) Object.setPrototypeOf(resProto, pristineResProto);
+      }
+    }
+  };
+}
+async function readPackageInfo(cwd) {
+  try {
+    const pkg = JSON.parse(await (0, import_promises.readFile)((0, import_node_path.join)(cwd, "package.json"), "utf8"));
+    return { name: pkg.name ?? "app", version: pkg.version ?? "0.0.0" };
+  } catch {
+    return { name: "app", version: "0.0.0" };
+  }
+}
+
+// src/index.ts
+var import_core3 = require("@exposify/core");
+var MCP_PATH = "/mcp";
+function aiReady(options = {}) {
+  const cfg = (0, import_core2.resolveOptions)(options);
+  const cwd = options.cwd ?? process.cwd();
+  const mounts = options.mounts;
+  try {
+    installMountRecorder();
+  } catch {
+  }
+  let handlerPromise = null;
+  let disabled = false;
+  let warned = false;
+  return (req, res, next) => {
+    const path = req.path ?? req.url.split("?")[0];
+    if (path !== MCP_PATH && !path.startsWith(`${MCP_PATH}/`)) return next();
+    if (disabled) {
+      res.writeHead(503).end("agentready is disabled due to an internal error");
+      return;
+    }
+    handlerPromise ??= initialize(req.app, cfg, cwd, mounts);
+    handlerPromise.then((handler) => handler(req, res)).catch((err) => {
+      disabled = true;
+      handlerPromise = null;
+      if (!warned) {
+        warned = true;
+        console.warn("[agentready] disabled after internal error:", err);
+      }
+      if (!res.headersSent) res.writeHead(503).end("agentready failed to initialize");
+    });
+  };
+}
+async function initialize(app, cfg, cwd, mounts) {
+  let surface = null;
+  let kbPromise = null;
+  const getSurface = async () => {
+    surface ??= await buildExpressSurface(app, cfg, cwd, { mounts });
+    return surface;
+  };
+  const getKb = async () => {
+    const s = await getSurface();
+    kbPromise ??= (0, import_node2.loadOrBuildKb)(s.docs, (0, import_node_path2.join)(cwd, ".agentready"));
+    return kbPromise;
+  };
+  await getSurface();
+  await getKb();
+  return (0, import_node2.createNodeMcpHandler)({ getSurface, getKb, cfg });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  aiReady,
+  describe,
+  exposed,
+  hidden,
+  routesFromExpress
+});

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { RouteInfo, AgentReadyOptions } from '@exposify/core';
+export { describe, exposed, hidden } from '@exposify/core';
+
+interface RoutesFromExpressOptions {
+    /**
+     * Explicit fallback for router (or sub-app) mounts the automatic
+     * mechanisms can't resolve -- most commonly a sub-app mounted via
+     * `app.use(path, subApp)`, whose real handle Express wraps in an opaque
+     * dispatch closure before storing it as `layer.handle` (see
+     * subAppMountOf's doc comment), so there is no reflectable trace of it on
+     * the app's router stack at all. Keyed by the mount prefix, valued by the
+     * exact router/app object registered at that prefix.
+     */
+    mounts?: Record<string, unknown>;
+}
+declare function routesFromExpress(app: unknown, opts?: RoutesFromExpressOptions): RouteInfo[];
+
+interface ExpressAiReadyOptions extends AgentReadyOptions {
+    /** Where docs globs and the .agentready cache resolve. Default: process.cwd() */
+    cwd?: string;
+    /**
+     * Explicit mount paths for routers (or sub-apps) introspection can't
+     * discover on its own -- most commonly a sub-app mounted via
+     * `app.use(path, subApp)`. On Express 5, an ordinary `app.use(path,
+     * router)` mount is discovered automatically as long as `aiReady()` is
+     * registered before it (the standard layout); this option is the
+     * fallback for anything mounted earlier, or that automatic discovery
+     * otherwise can't reach. Keyed by mount prefix, valued by the exact
+     * router/app object registered at that prefix.
+     */
+    mounts?: Record<string, unknown>;
+}
+declare function aiReady(options?: ExpressAiReadyOptions): (req: any, res: any, next: any) => void;
+
+export { type ExpressAiReadyOptions, aiReady, routesFromExpress };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { RouteInfo, AgentReadyOptions } from '@exposify/core';
+export { describe, exposed, hidden } from '@exposify/core';
+
+interface RoutesFromExpressOptions {
+    /**
+     * Explicit fallback for router (or sub-app) mounts the automatic
+     * mechanisms can't resolve -- most commonly a sub-app mounted via
+     * `app.use(path, subApp)`, whose real handle Express wraps in an opaque
+     * dispatch closure before storing it as `layer.handle` (see
+     * subAppMountOf's doc comment), so there is no reflectable trace of it on
+     * the app's router stack at all. Keyed by the mount prefix, valued by the
+     * exact router/app object registered at that prefix.
+     */
+    mounts?: Record<string, unknown>;
+}
+declare function routesFromExpress(app: unknown, opts?: RoutesFromExpressOptions): RouteInfo[];
+
+interface ExpressAiReadyOptions extends AgentReadyOptions {
+    /** Where docs globs and the .agentready cache resolve. Default: process.cwd() */
+    cwd?: string;
+    /**
+     * Explicit mount paths for routers (or sub-apps) introspection can't
+     * discover on its own -- most commonly a sub-app mounted via
+     * `app.use(path, subApp)`. On Express 5, an ordinary `app.use(path,
+     * router)` mount is discovered automatically as long as `aiReady()` is
+     * registered before it (the standard layout); this option is the
+     * fallback for anything mounted earlier, or that automatic discovery
+     * otherwise can't reach. Keyed by mount prefix, valued by the exact
+     * router/app object registered at that prefix.
+     */
+    mounts?: Record<string, unknown>;
+}
+declare function aiReady(options?: ExpressAiReadyOptions): (req: any, res: any, next: any) => void;
+
+export { type ExpressAiReadyOptions, aiReady, routesFromExpress };

package/dist/index.js

@@ -0,0 +1,362 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/index.ts
+import { join as join2 } from "path";
+import {
+  resolveOptions
+} from "@exposify/core";
+import {
+  createNodeMcpHandler,
+  loadOrBuildKb
+} from "@exposify/core/node";
+
+// src/surface.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { inject } from "light-my-request";
+import { loadDocsFromFs } from "@exposify/core/node";
+
+// src/introspect.ts
+import { getMarker } from "@exposify/core";
+
+// src/mount-registry.ts
+import { createRequire } from "module";
+var recordedMounts = /* @__PURE__ */ new WeakMap();
+var patchedTargets = /* @__PURE__ */ new WeakSet();
+function installMountRecorder(routerCtor) {
+  try {
+    const RouterCtor = routerCtor ?? resolveExpressRouter();
+    if (typeof RouterCtor !== "function") return;
+    const target = resolvePatchTarget(RouterCtor);
+    if (!target) return;
+    if (patchedTargets.has(target)) return;
+    patchedTargets.add(target);
+    const original = target.use;
+    if (typeof original !== "function") return;
+    const originalUse = original;
+    const wrapper = function(...args) {
+      try {
+        recordUse(this, args);
+      } catch {
+      }
+      return originalUse.apply(this, args);
+    };
+    Object.defineProperty(wrapper, "name", { value: "use" });
+    target.use = wrapper;
+  } catch {
+  }
+}
+function getRecordedMounts(handle) {
+  if (typeof handle !== "function") return void 0;
+  return recordedMounts.get(handle);
+}
+function resolveExpressRouter() {
+  const req = resolveRequireFn();
+  if (!req) return void 0;
+  const expressModule = req("express");
+  return expressModule.Router;
+}
+function resolveRequireFn() {
+  try {
+    if (typeof __require === "function" && typeof __require.resolve === "function") return __require;
+    return createRequire(import.meta.url);
+  } catch {
+    return void 0;
+  }
+}
+function resolvePatchTarget(RouterCtor) {
+  const proto = RouterCtor.prototype;
+  if (proto && typeof proto.use === "function") {
+    return proto;
+  }
+  if (typeof RouterCtor.use === "function") {
+    return RouterCtor;
+  }
+  return void 0;
+}
+function classifyFirstArg(first) {
+  let arg = first;
+  while (Array.isArray(arg) && arg.length !== 0) arg = arg[0];
+  if (typeof arg === "function") {
+    return { paths: ["/"], handlerOffset: 0 };
+  }
+  if (typeof first === "string") {
+    return { paths: [first], handlerOffset: 1 };
+  }
+  if (Array.isArray(first) && first.every((p) => typeof p === "string")) {
+    return { paths: first, handlerOffset: 1 };
+  }
+  return { paths: null, handlerOffset: 1 };
+}
+function recordUse(parent, args) {
+  if (args.length === 0) return;
+  const { paths, handlerOffset } = classifyFirstArg(args[0]);
+  if (paths === null) return;
+  const rawHandlers = args.slice(handlerOffset);
+  for (const fn of flattenHandlers(rawHandlers)) {
+    if (typeof fn !== "function") continue;
+    if (!Array.isArray(fn.stack)) continue;
+    const existing = recordedMounts.get(fn) ?? [];
+    for (const p of paths) {
+      if (!existing.some((e) => e.parent === parent && e.path === p)) {
+        existing.push({ parent, path: p });
+      }
+    }
+    recordedMounts.set(fn, existing);
+  }
+}
+function flattenHandlers(items) {
+  return items.flatMap((item) => Array.isArray(item) ? flattenHandlers(item) : [item]);
+}
+
+// src/introspect.ts
+function routesFromExpress(app, opts) {
+  const router = routerOf(app);
+  const out = [];
+  const walked = /* @__PURE__ */ new Map();
+  const unresolved = /* @__PURE__ */ new Set();
+  if (router?.stack) {
+    walk(router.stack, "", router, out, walked, unresolved);
+  }
+  if (opts?.mounts) {
+    for (const [prefix, handle] of Object.entries(opts.mounts)) {
+      try {
+        const resolved = ownerAndStackOf(handle);
+        if (!resolved) continue;
+        unresolved.delete(handle);
+        walkOnce(handle, prefix, resolved.stack, resolved.owner, out, walked, unresolved);
+      } catch {
+      }
+    }
+  }
+  if (unresolved.size > 0) warnMountSkipped();
+  return out;
+}
+var warnedAboutSkippedMount = false;
+function warnMountSkipped() {
+  if (warnedAboutSkippedMount) return;
+  warnedAboutSkippedMount = true;
+  try {
+    console.warn(
+      `[agentready] skipped one or more mounted routers: their mount path could not be determined automatically, so routes under them will not be exposed as tools. If aiReady() is registered before they're mounted, this is usually automatic (Express 5's mount recorder); otherwise pass them explicitly via aiReady({ mounts: { "/path": router } }).`
+    );
+  } catch {
+  }
+}
+function routerOf(app) {
+  if (!app || typeof app !== "object" && typeof app !== "function") return void 0;
+  const withRouter = app;
+  if (withRouter._router?.stack) return withRouter._router;
+  try {
+    return withRouter.router;
+  } catch {
+    return void 0;
+  }
+}
+function walk(stack, prefix, owner, out, walked, unresolved) {
+  for (const layer of stack) {
+    try {
+      if (layer.route) {
+        const path = joinPaths(prefix, layer.route.path);
+        const handlers = layer.route.stack.map((s) => s.handle);
+        const marker = handlers.map(getMarker).find(Boolean);
+        for (const [method, enabled] of Object.entries(layer.route.methods)) {
+          if (!enabled || method === "_all") continue;
+          out.push({
+            method: method.toUpperCase(),
+            path,
+            params: extractParams(path),
+            marker,
+            description: marker?.kind === "described" ? marker.description : void 0
+          });
+        }
+        continue;
+      }
+      const handle = layer.handle;
+      if (handle === void 0 || handle === null) continue;
+      const mountPaths = /* @__PURE__ */ new Set();
+      const recorded = getRecordedMountPaths(handle, owner);
+      if (recorded) for (const p of recorded) mountPaths.add(p);
+      const regexpMount = mountPathOf(layer);
+      if (regexpMount !== null) mountPaths.add(regexpMount);
+      const subAppMount = subAppMountOf(handle);
+      if (subAppMount !== null) mountPaths.add(subAppMount);
+      const resolved = mountPaths.size > 0 && walkEachVia([...mountPaths], handle, prefix, out, walked, unresolved);
+      if (resolved) continue;
+      if (looksRouterish(handle) || looksLikeExpressApp(handle)) {
+        unresolved.add(handle);
+      }
+    } catch {
+    }
+  }
+}
+function getRecordedMountPaths(handle, owner) {
+  const recorded = getRecordedMounts(handle);
+  if (!recorded) return null;
+  const paths = recorded.filter((entry) => entry.parent === owner).map((entry) => entry.path);
+  return paths.length > 0 ? paths : null;
+}
+function walkEachVia(mounts, handle, prefix, out, walked, unresolved) {
+  const resolved = ownerAndStackOf(handle);
+  if (!resolved) return false;
+  unresolved.delete(handle);
+  for (const mount of mounts) {
+    walkOnce(handle, joinPaths(prefix, mount), resolved.stack, resolved.owner, out, walked, unresolved);
+  }
+  return true;
+}
+function walkOnce(handle, prefix, stack, owner, out, walked, unresolved) {
+  let prefixes = walked.get(handle);
+  if (prefixes?.has(prefix)) return;
+  if (!prefixes) {
+    prefixes = /* @__PURE__ */ new Set();
+    walked.set(handle, prefixes);
+  }
+  prefixes.add(prefix);
+  walk(stack, prefix, owner, out, walked, unresolved);
+}
+function mountPathOf(layer) {
+  if (layer.regexp?.fast_slash) return "";
+  const source = layer.regexp?.source;
+  if (!source) return null;
+  const match = /^\^((?:\\\/[A-Za-z0-9._~-]+)+)\\\/\?(?:\(\?=\\\/\|\$\)|\$)/.exec(source);
+  if (!match) return null;
+  return match[1].replace(/\\\//g, "/");
+}
+function joinPaths(a, b) {
+  const joined = `${a}${b.startsWith("/") ? b : `/${b}`}`;
+  return joined.replace(/\/+/g, "/").replace(/(.)\/$/, "$1") || "/";
+}
+function extractParams(path) {
+  return [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((m) => m[1]);
+}
+function looksRouterish(handle) {
+  return Array.isArray(handle?.stack);
+}
+function looksLikeExpressApp(handle) {
+  if (typeof handle !== "function") return false;
+  const h = handle;
+  return typeof h.handle === "function" && typeof h.set === "function";
+}
+function subAppMountOf(handle) {
+  if (!looksLikeExpressApp(handle)) return null;
+  const mountpath = handle.mountpath;
+  const value = Array.isArray(mountpath) ? mountpath[0] : mountpath;
+  if (typeof value !== "string" || value === "/") return null;
+  return value;
+}
+function ownerAndStackOf(handle) {
+  const direct = handle?.stack;
+  if (Array.isArray(direct)) return { owner: handle, stack: direct };
+  const sub = routerOf(handle);
+  if (sub?.stack) return { owner: sub, stack: sub.stack };
+  return void 0;
+}
+
+// src/surface.ts
+async function buildExpressSurface(app, cfg, cwd, opts) {
+  const info = await readPackageInfo(cwd);
+  const appish = app;
+  if (!appish.request || !appish.response) {
+    console.warn(
+      "[agentready] express request/response prototypes not found; light-my-request corruption guard inactive"
+    );
+  }
+  const reqProto = appish.request ? Object.getPrototypeOf(appish.request) : void 0;
+  const resProto = appish.response ? Object.getPrototypeOf(appish.response) : void 0;
+  const pristineReqProto = reqProto ? Object.getPrototypeOf(reqProto) : void 0;
+  const pristineResProto = resProto ? Object.getPrototypeOf(resProto) : void 0;
+  return {
+    info,
+    routes: routesFromExpress(app, opts),
+    docs: await loadDocsFromFs(cfg.docs, cwd),
+    async dispatch(req) {
+      const url = new URL(req.url);
+      try {
+        const res = await inject(app, {
+          method: req.method,
+          url: url.pathname + url.search,
+          headers: Object.fromEntries(req.headers.entries()),
+          payload: req.body ? await req.text() : void 0
+        });
+        return new Response(res.body, {
+          status: res.statusCode,
+          headers: res.headers
+        });
+      } finally {
+        if (pristineReqProto && reqProto) Object.setPrototypeOf(reqProto, pristineReqProto);
+        if (pristineResProto && resProto) Object.setPrototypeOf(resProto, pristineResProto);
+      }
+    }
+  };
+}
+async function readPackageInfo(cwd) {
+  try {
+    const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+    return { name: pkg.name ?? "app", version: pkg.version ?? "0.0.0" };
+  } catch {
+    return { name: "app", version: "0.0.0" };
+  }
+}
+
+// src/index.ts
+import { exposed, hidden, describe } from "@exposify/core";
+var MCP_PATH = "/mcp";
+function aiReady(options = {}) {
+  const cfg = resolveOptions(options);
+  const cwd = options.cwd ?? process.cwd();
+  const mounts = options.mounts;
+  try {
+    installMountRecorder();
+  } catch {
+  }
+  let handlerPromise = null;
+  let disabled = false;
+  let warned = false;
+  return (req, res, next) => {
+    const path = req.path ?? req.url.split("?")[0];
+    if (path !== MCP_PATH && !path.startsWith(`${MCP_PATH}/`)) return next();
+    if (disabled) {
+      res.writeHead(503).end("agentready is disabled due to an internal error");
+      return;
+    }
+    handlerPromise ??= initialize(req.app, cfg, cwd, mounts);
+    handlerPromise.then((handler) => handler(req, res)).catch((err) => {
+      disabled = true;
+      handlerPromise = null;
+      if (!warned) {
+        warned = true;
+        console.warn("[agentready] disabled after internal error:", err);
+      }
+      if (!res.headersSent) res.writeHead(503).end("agentready failed to initialize");
+    });
+  };
+}
+async function initialize(app, cfg, cwd, mounts) {
+  let surface = null;
+  let kbPromise = null;
+  const getSurface = async () => {
+    surface ??= await buildExpressSurface(app, cfg, cwd, { mounts });
+    return surface;
+  };
+  const getKb = async () => {
+    const s = await getSurface();
+    kbPromise ??= loadOrBuildKb(s.docs, join2(cwd, ".agentready"));
+    return kbPromise;
+  };
+  await getSurface();
+  await getKb();
+  return createNodeMcpHandler({ getSurface, getKb, cfg });
+}
+export {
+  aiReady,
+  describe,
+  exposed,
+  hidden,
+  routesFromExpress
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@exposify/express",
+  "version": "0.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@exposify/core": "0.0.0",
+    "light-my-request": "^6.0.0"
+  },
+  "peerDependencies": {
+    "express": ">=4 <6"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "express": "npm:express@^5.1.0",
+    "express4": "npm:express@^4.19.0",
+    "express5": "npm:express@^5.1.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}