@exposify/express 0.3.7 → 0.3.9

package/README.md

@@ -17,6 +17,267 @@ credentials (`Authorization`/`Cookie`), forwarded to your routes unchanged.
 There is no separate authorization layer to configure or get wrong — an
 agent can do exactly what the person it's acting for could already do.
 
+## NestJS
+
+NestJS on its default Express platform works with this package as it is. Add
+one line to `main.ts`, after `NestFactory.create()` and before `listen()`:
+
+```ts
+const app = await NestFactory.create(AppModule);
+app.setGlobalPrefix("api");
+app.use(aiReady({ expose: ["POST /api/v1/orders"] })); // paths as Nest serves them
+await app.listen(3000);
+```
+
+Tools get Nest's full paths (global prefix, URI versioning, `RouterModule`
+paths), and tool calls go through Nest itself: guards, pipes, interceptors
+and exception filters apply exactly as for any HTTP client, so a guarded
+route refuses an agent without credentials and a `ValidationPipe` error
+reaches the agent as an actionable 400. `npx exposify-express setup` and
+`inspect` find `src/main.ts` from `nest-cli.json` and load it with your
+`ts-node`/`swc-node`. The Fastify platform isn't supported yet. See
+`examples/nest-demo`.
+
+With `@nestjs/swagger`, [`@exposify/nestjs`](../nestjs) does this in one line
+(`mountAiReady(app)`) and adds `@McpExposed()` / `@McpHidden()` /
+`@McpDescribe()` decorators. Or pass the document yourself, and tools get its
+DTO schemas and `@ApiOperation` summaries:
+
+```ts
+const openapi = SwaggerModule.createDocument(app, new DocumentBuilder().build());
+app.use(aiReady({ expose: ["POST /api/v1/orders"], openapi }));
+```
+
+Agents then get validated inputs (a `minimum: 1` rejects `qty: 0` before any
+request is made) and your summaries as tool descriptions. `openapi` also
+takes a path to a JSON file, for any Express app with an OpenAPI document.
+Description precedence: `describe()` in code, then
+`exposify.descriptions.json`, then OpenAPI, then the derived text.
+
+## Guided setup: `npx exposify-express setup`
+
+Instead of writing the config by hand, run this in your app's directory:
+
+```bash
+npx exposify-express setup
+```
+
+It loads your app without starting a server, lists every endpoint (reads
+pre-selected), asks whether to print the startup line, then prints the
+`aiReady()` config for your choices, copies it to the clipboard, and tells
+you the file and line to paste it at. Press Enter after pasting and it
+re-scans to confirm agents get exactly what you picked. Last, it offers to
+give your tools real descriptions (below).
+
+- **Checklist keys:** space toggles, `a` all, `n` none, `r` reads only, `/`
+  filters. Routes wrapped in `exposed()`/`hidden()`/`describe()` are shown
+  locked: the code decides them.
+- **`!` exposes everything** (`expose: "*"`), after you type `expose all`.
+  That includes write routes added to your app later, with no review, so the
+  generated config carries a warning comment and the startup line says so on
+  every boot. `x` goes back to an explicit list. Ticking every row with `a`
+  never produces `"*"`.
+- **Finding your app:** the entry file comes from `--entry`, else your
+  `dev`/`start` script, `main`, or `src/{main,server,index,app}`. TypeScript
+  runs through your project's own `tsx`, `ts-node` or `@swc-node/register`.
+  Code that runs at import time (DB clients, timers) does run, in a child
+  process that's discarded; no port is ever bound. An app that never calls
+  `listen()` is read once it stops registering routes.
+- **`.env`:** if your project has one, `setup` first asks whether to load it
+  into the scan (default yes), since apps often refuse to start without
+  their secrets. Values go only to the scan's process and are never printed;
+  variables already set in your shell win. `--env-vars <path>` loads a
+  specific file (also for `inspect` and `--ci`, which never load one
+  otherwise), `--no-env-vars` skips it.
+- **Skipping questions:** `--quick` keeps the defaults (reads, or your current
+  config) and the current startup-log setting, but still copies the config
+  and verifies the paste. `--apply` makes the change in your code instead
+  (setup asks in a terminal; `--no-apply` never does): it rewrites only the
+  options setup manages in your `aiReady()` call, or adds the call and its
+  import, and falls back to the paste instructions if it can't do that
+  safely. Check it with `git diff`. `--expose "POST /orders"` (repeatable),
+  `--expose-all` and `--startup-log on|off` answer one question each.
+- **Scripts and CI:** `--ci` never prompts, never touches the clipboard and
+  prints no colors; it fails instead of asking. It turns on by itself when
+  the `CI` environment variable is set.
+- **How your users sign in** (step 4): `setup` reads your `package.json`.
+  With Auth0, Clerk, WorkOS or Kinde it points you at the `oauth` option
+  (your provider already signs agents in). Otherwise it offers Exposify's
+  hosted broker and a browser sign-in that writes `EXPOSIFY_KEY` to `.env`
+  (a new project named after your app, or an existing one). `--no-sign-in`
+  skips the step; `EXPOSIFY_NO_BROWSER=1` prints the link instead of
+  opening it.
+
+**Tool descriptions.** Agents pick tools by their descriptions, and by default
+they get one derived from the route ("Create an order (POST /orders)").
+`setup`'s step 5, or `npx exposify-express describe` any time, replaces those:
+
+- `a` sends each route's handler source to Exposify's description service,
+  which writes a proposal with an LLM (`--no-source` sends only method, path
+  and middleware names). Strings that look like secrets are masked on your
+  machine first, and the CLI says exactly what it's about to send and where. The
+  service may log each request with your IP address (it tells you how long
+  it keeps them).
+  Each proposal is shown: Enter accepts, `e` edits, `r` regenerates, `s`
+  skips. `A` accepts the remaining **read** routes; a write route's
+  description is always reviewed on its own, since a wrong claim about what
+  a write does is the worst thing an agent can be told. You don't need an
+  LLM key: without an account you get a small free allowance (2 routes a
+  day by default); when it runs out, the CLI links to a free sign-up and takes your project's secret key
+  (and offers to save it in `~/.config/exposify/credentials.json`, readable
+  only by you). `--license-key` / `EXPOSIFY_KEY` pass one directly;
+  `--api-url` / `EXPOSIFY_API_URL` point at another service.
+- `w` lets you write them yourself (`e` opens `$EDITOR`).
+
+They're saved to `exposify.descriptions.json`, which `aiReady()` loads at
+startup (`descriptions: "path"` or `false` to change that); `describe()` text
+in your code still wins. Text you wrote or edited is never overwritten. When
+a route's handler changes, its AI description is offered again; yours is
+flagged for you to check. In CI, `describe --check` exits 1 if a tool has no
+description or one is out of date, and `describe --ci` writes AI
+descriptions for read routes only, listing the writes for a person.
+
+`npx exposify-express inspect` prints every route with its tool name,
+whether agents get it, and why (`--json` for scripts): the answer to "why
+isn't my route showing up?".
+
+**Catch tool changes in CI:** `npx exposify-express inspect --snapshot` writes
+`exposify.tools.json` (each route agents can call, and its tool name).
+`setup` offers to save the same file as its last question (default no;
+`--snapshot` to save without asking). Commit it, and run
+`npx exposify-express inspect --check` in CI: it exits 1,
+listing what changed, when a route becomes a tool (writes flagged), stops
+being one, or gets a new tool name. Re-run `--snapshot` when the change is
+intended, so it shows up in the PR diff for review.
+
+## 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, with no code:
+
+- On the first request, `aiReady()` finds your login among your routes: a
+  `POST` route whose handler reads a password and something saying who from
+  `req.body`, and sets a cookie, a session (`req.session`, passport's
+  `req.login`) or signs a token. Sign-up, sign-out and reset routes are never
+  picked.
+- When Claude connects, the person clicks Allow on Exposify's page and lands
+  on a sign-in form served at `/mcp/login`, on your domain. On submit,
+  `aiReady()` sends your login route the fields through your own app (no
+  browser cookies, the person's address forwarded), and the session it
+  creates goes to the broker for this connection. Every tool call then runs
+  as that person; cookies you set later are kept; a 401 or a redirect to the
+  login ends the connection, so the assistant asks to connect again.
+- `aiReady()` tells Exposify about the login and its MCP address before
+  answering `/mcp`, so there's nothing to add in the dashboard.
+
+`login: { path, fields, body? }` names another route; `login: false` turns
+it off. Routers introspection can't see (sub-apps) need `mounts`.
+
+## "Click Connect and log in" (OAuth)
+
+By default the MCP client has to be handed a token by hand. If your app's
+auth provider is an OAuth 2.1 authorization server (Auth0, WorkOS, Clerk,
+Okta, Keycloak, Supabase Auth, ...), add `oauth` and MCP clients log in on
+their own:
+
+```ts
+app.use(aiReady({
+  oauth: {
+    issuer: "https://acme.us.auth0.com/",   // exactly the tokens' `iss`
+    resource: "https://api.acme.com/mcp",   // the public MCP URL = required token audience
+    scopes: ["read"],                       // optional
+  },
+}));
+```
+
+The whole `/mcp` endpoint then requires a valid access token. A request
+without one gets `401` + `WWW-Authenticate: Bearer resource_metadata="…"`,
+and Protected Resource Metadata (RFC 9728) is served at
+`/.well-known/oauth-protected-resource[/mcp]`. That is enough for Claude,
+Cursor, etc. to discover your issuer, register, open your real login page
+and refresh tokens later, with nothing for the user to paste. Tokens are
+verified as JWTs against the issuer's JWKS (discovered from its metadata):
+signature, `iss`, `aud` = `resource`, expiry, and `scopes`. An expired
+token is an HTTP `401` (so the client refreshes), and an unreachable
+issuer is a `503`, never a pass.
+
+Then the validated `Authorization` is forwarded to your routes in-process,
+exactly like passthrough.
+
+### One change in your app: accept the MCP audience
+
+MCP tokens are issued for the MCP URL (`aud: "https://api.acme.com/mcp"`),
+and most JWT middleware rejects any audience it wasn't told about. So add
+the MCP URL next to your existing audience. Your web app's tokens keep
+working:
+
+```ts
+const MCP_URL = "https://api.acme.com/mcp";
+app.use(aiReady({ oauth: { issuer: ISSUER, resource: MCP_URL } }));
+
+// express-oauth2-jwt-bearer (Auth0):
+app.use(auth({ issuerBaseURL: ISSUER, audience: ["https://api.acme.com", MCP_URL] }));
+
+// or jose directly:
+await jwtVerify(token, JWKS, { issuer: ISSUER, audience: ["https://api.acme.com", MCP_URL] });
+```
+
+Any other middleware works the same way: pass both values wherever it takes
+the expected audience. On the provider side, the issuer must be willing to
+mint tokens for the MCP URL. In Auth0, for example, add an API whose
+identifier is the MCP URL, and leave your existing API alone.
+
+If you miss this, sign-in still succeeds but every tool call fails. The
+first time your app answers `401` to a token the MCP endpoint already
+validated, `aiReady()` logs one warning naming the audience to add and
+quoting your app's own `WWW-Authenticate` header.
+
+- `resource` is required, never inferred from `Host` (proxies get it
+  wrong). Use your public URL; `http` is only accepted for `localhost`.
+- `audience` overrides the expected `aud` for issuers that can't bind
+  tokens to `resource`. It's weaker: any token for that audience passes,
+  and a warning is logged at startup.
+- `jwksUri` skips metadata discovery. `verify: async (token) => claims | null`
+  replaces JWT verification (opaque tokens, introspection).
+- A custom `auth` resolver receives `(headers, { claims })`, so it can map
+  the validated user to whatever your app expects.
+- `oauth` can't be combined with `docsAuth: "public"` (that throws): clients
+  only start login on a connect-time `401`, so the docs tools are behind
+  the token too.
+- Apps without an OAuth authorization server (session cookies,
+  passport-local, homegrown JWTs) need one first; this package doesn't
+  include one.
+
+## Startup log
+
+On boot (`npm run dev`, or in production), right after your routes
+register, `aiReady()` prints one line saying whether MCP is up:
+
+```
+[agentready] MCP ready at /mcp: 6 tools (4 read, 1 write, search_docs), 1 write route hidden (opt in with exposed()), 2 docs indexed, auth: passthrough
+```
+
+When something's wrong, the line names the problem and a fix instead:
+
+```
+[agentready] MCP failed to start: <reason>
+  fix: <what to do>
+[agentready] warning: MCP is up at /mcp but exposes no route tools
+  fix: register app.use(aiReady()) before your routers, ...
+[agentready] warning: can't verify access tokens from oauth.issuer https://...: <reason>
+  fix: make oauth.issuer match the tokens' `iss` exactly ...
+```
+
+- With `oauth`, the issuer's metadata and keys are fetched once at boot, so
+  a wrong issuer shows up here instead of on the first login.
+- Routes registered later (e.g. after an `await`) are picked up on the first
+  `/mcp` request, which prints an updated line only if the count changed.
+- Failures and warnings always print. The ready line is on by default and
+  off under `NODE_ENV=test`. `startupLog: true | false` overrides that
+  (and also turns the issuer check on or off).
+- The check is read-only and never throws into your app; your own routes
+  keep working either way.
+
 ## Exposure policy
 
 - **Reads (GET/HEAD) are exposed automatically.** Writes are hidden by
@@ -36,6 +297,11 @@ app.post("/orders/:id/refund", describe(refundOrder, {
 }));
 ```
 
+- **Hiding one method on a path:** `exclude` takes picomatch globs on the
+  path (`"/admin/**"`, hides every method), or `"METHOD /path"` entries that
+  match one method and that exact path. `exclude: ["GET /orders"]` with
+  `expose: ["POST /orders"]` hides the read and keeps the write.
+
 - **`describe()`'s `input` envelope contract:** `input` is a flat Zod shape.
   At call time, each top-level key is routed by name — a key matching one of
   the route's `:param` segments becomes a path substitution, `query`
@@ -60,15 +326,20 @@ app.use(aiReady({ mounts: { "/legacy": legacyRouter } }));
 
 ```ts
 aiReady({
-  auth?: "passthrough" | "none",        // default "passthrough"
+  auth?: "passthrough" | "none" | AuthResolver, // default "passthrough"
+  oauth?: { issuer, resource, scopes?, audience?, jwksUri?, verify? }, // see above
+  startupLog?: boolean,                  // default on, off under NODE_ENV=test
   docs?: string[],                       // default ["README.md", "docs/**/*.md"]
   expose?: string[] | "*",               // e.g. ["GET /trends"]; default unset
-  exclude?: string[],                    // picomatch globs against the route path
-  docsAuth?: "public" | "required",      // default "public"
+  exclude?: string[],                    // path globs, or "METHOD /path" for one method
+  docsAuth?: "public" | "required",      // default "public" ("required" with oauth or the hosted broker)
   embedder?: (texts: string[]) => Promise<number[][]>,
   telemetry?: { enabled: boolean; sink?(event): void; capturePayloads?: boolean },
   cwd?: string,                          // default process.cwd()
   mounts?: Record<string, unknown>,      // explicit router/sub-app overrides
+  descriptions?: string | false,         // default "exposify.descriptions.json" if present
+  openapi?: string | object,             // your OpenAPI document: tool schemas + descriptions
+  login?: false | { path, fields, body? }, // your own login, for the hosted broker (found by itself)
 });
 ```
 
@@ -84,10 +355,16 @@ default above.
   only works when `aiReady()` is registered *before* the mount. A router
   mounted both before and after `aiReady()` ("straddle" mount) resolves
   correctly on Express 4 but silently drops the earlier prefix on Express 5.
-- In-process dispatch uses `light-my-request`, which splices Express's
-  process-wide request/response prototypes for the duration of each
-  dispatch — a narrow concurrency window under real concurrent traffic, a
-  known tradeoff tracked in `packages/express/src/surface.ts`.
+- With `oauth`, only a global `scopes` set is checked at the edge; per-tool
+  scopes aren't supported (your routes' own `403`s still come back as tool
+  errors). Combining `oauth` with the hosted broker's resolver isn't supported
+  yet.
+- Tool calls are dispatched as real HTTP requests to a private listener on
+  `127.0.0.1` (an ephemeral port, opened on the first tool call, refusing
+  anything but the SDK's own requests). Each call carries the MCP caller's
+  socket address, `Host` and `Forwarded`/`X-Forwarded-*` headers, so
+  `req.ip`, `req.hostname`, `req.protocol` and `trust proxy` see the agent
+  exactly as they would for a direct request, never as localhost.
 
 See the repo README for
 the full picture across all `@exposify/*` packages, including

package/dist/cli.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+
+// bin/exposify-express.ts
+import { runCli } from "@exposify/cli";
+
+// bin/adapter.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { insertAiReadyCall, renderConfig, replaceAiReadyOptions } from "@exposify/cli";
+
+// bin/paste-hint.ts
+var relative = (site, cwd) => site.file.startsWith(`${cwd}/`) ? site.file.slice(cwd.length + 1) : site.file;
+function placement(scan) {
+  const firstMount = scan.uses.find((u) => (u.kind === "router" || u.kind === "app") && u.site)?.site;
+  const before = [firstMount, scan.firstRouteAt].filter((s) => Boolean(s)).sort((a, b) => a.line - b.line)[0];
+  const file = before?.file ?? scan.createdAt?.file;
+  if (!file) return void 0;
+  const plain = scan.uses.filter((u) => u.kind === "middleware" && u.site?.file === file && (!before || u.site.line < before.line));
+  const after = plain.at(-1)?.site ?? (scan.createdAt?.file === file ? scan.createdAt : void 0);
+  return { file, ...before ? { beforeLine: before.line } : {}, ...after ? { afterLine: after.line } : {} };
+}
+function pasteHint(scan, cwd, readLine) {
+  const quote = (site) => {
+    const text = readLine(site)?.trim();
+    return text ? `  ${text}` : "";
+  };
+  const firstMount = scan.uses.find((u) => (u.kind === "router" || u.kind === "app") && u.site)?.site;
+  const before = [firstMount, scan.firstRouteAt].filter((s) => Boolean(s)).sort((a, b) => a.line - b.line)[0];
+  if (scan.aiReady?.site) {
+    const site = scan.aiReady.site;
+    const fn = readLine(site)?.includes("mountAiReady(") ? "mountAiReady" : "aiReady";
+    const out = { lines: [`Replace the ${fn}(...) call at ${relative(site, cwd)}:${site.line} with it.`] };
+    if (before && before.file === site.file && before.line < site.line) {
+      const where = `${relative(before, cwd)}:${before.line}`;
+      out.warning = scan.expressMajor >= 5 ? `aiReady() is after your routers (${where}). On Express 5 it only finds routers mounted after it: move it above that line.` : `aiReady() is after your routers (${where}). That works on Express 4, but moving it above that line keeps it working if you upgrade to Express 5.`;
+    }
+    return out;
+  }
+  const file = before?.file ?? scan.createdAt?.file;
+  if (!file) return { lines: ["Paste it in the file where you call express(), after your body parsers and before your routes."] };
+  const plain = scan.uses.filter(
+    (u) => u.kind === "middleware" && u.site?.file === file && (!before || u.site.line < before.line)
+  );
+  const after = plain.at(-1)?.site ?? (scan.createdAt?.file === file ? scan.createdAt : void 0);
+  const lines = [`Paste it in ${relative({ file, line: 0 }, cwd)}:`];
+  if (after) lines.push(`after line ${after.line}${quote(after)}`);
+  if (before) {
+    const why = scan.expressMajor >= 5 ? "<- must come before your routers (Express 5 only finds routers mounted after aiReady())" : "<- recommended: keeps working on Express 5, and no router can catch /mcp first";
+    lines.push(`before line ${before.line}${quote(before)}   ${why}`);
+  }
+  return { lines };
+}
+
+// bin/scan/entry.ts
+import { existsSync, readFileSync } from "fs";
+import { createRequire } from "module";
+import { dirname, extname, join, resolve } from "path";
+var realFs = {
+  exists: existsSync,
+  read: (path) => {
+    try {
+      return readFileSync(path, "utf8");
+    } catch {
+      return void 0;
+    }
+  }
+};
+var RUNNERS = /(?:^|\s|&&|;)(?:npx\s+)?(?:tsx(?:\s+watch)?|ts-node(?:-dev)?|node(?:mon)?|bun)\s+((?:--?[\w-]+(?:[= ](?!\S*\.[cm]?[jt]s\b)\S+)?\s+)*)([^\s"';&|]+\.[cm]?[jt]sx?)\b/;
+var CANDIDATES = ["main", "server", "index", "app"].flatMap(
+  (name) => ["ts", "js", "mjs", "cjs", "mts", "cts"].flatMap((ext) => [`src/${name}.${ext}`, `${name}.${ext}`])
+);
+function entryFromScript(script) {
+  return RUNNERS.exec(script)?.[2];
+}
+function detectEntry(cwd, explicit, fs = realFs) {
+  if (explicit) return { entry: resolve(cwd, explicit), via: "--entry" };
+  const pkgText = fs.read(join(cwd, "package.json"));
+  let pkg = {};
+  try {
+    pkg = pkgText ? JSON.parse(pkgText) : {};
+  } catch {
+  }
+  if (isNest(pkg)) {
+    const nestEntry = nestCliEntry(cwd, fs);
+    if (nestEntry) return { entry: nestEntry, via: "nest-cli.json" };
+  }
+  for (const name of ["dev", "start"]) {
+    const script = pkg.scripts?.[name];
+    const file = script ? entryFromScript(script) : void 0;
+    if (file && fs.exists(join(cwd, file))) return { entry: join(cwd, file), via: `scripts.${name}` };
+  }
+  if (pkg.main && fs.exists(join(cwd, pkg.main))) return { entry: join(cwd, pkg.main), via: "package.json main" };
+  for (const file of CANDIDATES) {
+    if (fs.exists(join(cwd, file))) return { entry: join(cwd, file), via: file };
+  }
+  return void 0;
+}
+function isNest(pkg) {
+  return Boolean(pkg.dependencies?.["@nestjs/core"] ?? pkg.devDependencies?.["@nestjs/core"]);
+}
+function nestCliEntry(cwd, fs) {
+  let cfg = {};
+  try {
+    cfg = JSON.parse(fs.read(join(cwd, "nest-cli.json")) ?? "{}");
+  } catch {
+  }
+  const file = join(cwd, cfg.sourceRoot ?? "src", `${cfg.entryFile ?? "main"}.ts`);
+  return fs.exists(file) ? file : void 0;
+}
+var TS_EXT = /* @__PURE__ */ new Set([".ts", ".mts", ".cts", ".tsx"]);
+function loadersFor(entry, cwd, fs = realFs) {
+  if (!TS_EXT.has(extname(entry))) return [{ name: "node", nodeArgs: [], env: {}, preload: "import" }];
+  const has = (mod) => {
+    try {
+      createRequire(join(cwd, "package.json")).resolve(mod);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const pkg = fs.read(join(cwd, "package.json")) ?? "{}";
+  let isEsm = false;
+  try {
+    isEsm = JSON.parse(pkg).type === "module";
+  } catch {
+  }
+  const loaders = [];
+  const tsx = { name: "tsx", nodeArgs: ["--import", "tsx"], env: {}, preload: "import" };
+  if (has("tsx")) loaders.push(tsx);
+  if (has("ts-node") && !isEsm) {
+    loaders.push({
+      name: "ts-node (transpile-only)",
+      nodeArgs: ["--require", "ts-node/register"],
+      // Projects often keep `module: esnext` in tsconfig.json for a bundler
+      // while running as CommonJS; force what Node will actually load.
+      env: { TS_NODE_TRANSPILE_ONLY: "1", TS_NODE_COMPILER_OPTIONS: JSON.stringify({ module: "commonjs" }) },
+      preload: "require"
+    });
+  }
+  if (has("@swc-node/register") && !isEsm) {
+    loaders.push({ name: "@swc-node/register", nodeArgs: ["--require", "@swc-node/register"], env: {}, preload: "require" });
+  }
+  loaders.push({ name: "node (built-in type stripping)", nodeArgs: [], env: {}, preload: "import" });
+  let parsed = {};
+  try {
+    parsed = JSON.parse(pkg);
+  } catch {
+  }
+  if (isNest(parsed)) {
+    const emitsMetadata = (l) => l.name.startsWith("ts-node") || l.name.startsWith("@swc-node");
+    return [...loaders.filter(emitsMetadata), ...loaders.filter((l) => !emitsMetadata(l))];
+  }
+  return loaders;
+}
+function projectRoot(entry, fs = realFs) {
+  let dir = dirname(entry);
+  for (; ; ) {
+    if (fs.exists(join(dir, "package.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return dirname(entry);
+    dir = parent;
+  }
+}
+
+// bin/scan/run.ts
+import { fork } from "child_process";
+import { dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+// bin/scan/env.ts
+var SCAN_ENV = {
+  entry: "EXPOSIFY_SCAN_ENTRY",
+  /** Set to "1" in the child so an app can skip heavy boot work if it wants. */
+  flag: "EXPOSIFY_SCAN",
+  /** How long to wait for listen() after the last route registration (ms). */
+  quietMs: "EXPOSIFY_SCAN_QUIET_MS"
+};
+
+// bin/scan/run.ts
+var LOADER_FAILURE = /ERR_MODULE_NOT_FOUND|ERR_UNKNOWN_FILE_EXTENSION|ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX|ERR_REQUIRE_ESM|Cannot find module|SyntaxError|Unexpected token|ERR_INVALID_TYPESCRIPT_SYNTAX|is not supported|TS\d{4}/;
+function preloadFor(loader, dir = dirname2(fileURLToPath(import.meta.url))) {
+  return loader.preload === "require" ? ["--require", join2(dir, "scan-preload.cjs")] : ["--import", pathToFileURL(join2(dir, "scan-preload.js")).href];
+}
+function runOnce(opts, loader) {
+  return new Promise((resolve2) => {
+    let output = "";
+    let message;
+    const child = fork(opts.entry, [], {
+      cwd: opts.cwd,
+      execArgv: [...loader.nodeArgs, ...preloadFor(loader, opts.preloadDir)],
+      env: {
+        ...opts.env,
+        ...process.env,
+        ...loader.env,
+        [SCAN_ENV.entry]: opts.entry,
+        [SCAN_ENV.flag]: "1",
+        ...opts.quietMs !== void 0 ? { [SCAN_ENV.quietMs]: String(opts.quietMs) } : {}
+      },
+      stdio: ["ignore", "pipe", "pipe", "ipc"]
+    });
+    child.stdout?.on("data", (chunk) => output += chunk);
+    child.stderr?.on("data", (chunk) => output += chunk);
+    child.on("message", (m) => message = m);
+    child.on("error", (err) => {
+      output += String(err);
+    });
+    child.on("exit", (code) => resolve2({ message, output, code }));
+  });
+}
+async function scanApp(opts) {
+  const loaders = loadersFor(opts.entry, opts.cwd);
+  let last;
+  for (const loader of loaders) {
+    const { message, output, code } = await runOnce(opts, loader);
+    if (message?.ok) return { ok: true, result: message, loader: loader.name };
+    const failure = message && !message.ok ? message : { ok: false, error: `the app exited (code ${code}) before it could be scanned` };
+    last = { ok: false, failure, output, loader: loader.name };
+    const text = `${failure.error}
+${output}`;
+    if (!LOADER_FAILURE.test(text)) break;
+  }
+  if (last && !last.ok && loaders.length > 1 && LOADER_FAILURE.test(`${last.failure.error}
+${last.output}`)) {
+    last.failure.fix ??= "none of the project's TypeScript loaders could run it; `npm i -D tsx` usually fixes this, or pass a built .js file with --entry";
+  }
+  return last;
+}
+
+// bin/adapter.ts
+var expressAdapter = {
+  bin: "exposify-express",
+  entryExample: "src/server.ts",
+  entryHelp: "The file that creates your Express app",
+  locate(cwd, entryFlag) {
+    const found = detectEntry(cwd, entryFlag);
+    return found ? { entry: found.entry, root: projectRoot(found.entry), via: found.via } : void 0;
+  },
+  async scan(location, env) {
+    const outcome = await scanApp({ entry: location.entry, cwd: location.root, env });
+    if (outcome.ok) return { ok: true, result: outcome.result };
+    return {
+      ok: false,
+      error: outcome.failure.error,
+      ...outcome.failure.fix ? { fix: outcome.failure.fix } : {},
+      output: outcome.output,
+      ...outcome.loader ? { loader: outcome.loader } : {}
+    };
+  },
+  configStep({ result, config, current, root, readLine }) {
+    const viaNest = Boolean(result.aiReady?.site && readLine(result.aiReady.site)?.includes("mountAiReady("));
+    const otherKeys = viaNest ? current?.otherKeys.filter((k) => k !== "openapi") : current?.otherKeys;
+    let code = renderConfig(config, { ...result.aiReady ? {} : { importFrom: "@exposify/express" }, ...otherKeys ? { otherKeys } : {} });
+    if (viaNest) {
+      code = code === "app.use(aiReady());" ? "mountAiReady(app); // keep swaggerConfig if you pass it" : code.replace(/^app\.use\(aiReady\(\{/m, "mountAiReady(app, {\n  // keep swaggerConfig if you pass it").replace(/\}\)\);$/m, "});");
+    }
+    return { code, hint: pasteHint(result, root, readLine), apply: applyStep(result, config, viaNest, root, code) };
+  }
+};
+var rel = (file, root) => file.startsWith(`${root}/`) ? file.slice(root.length + 1) : file;
+function applyStep(result, config, viaNest, root, code) {
+  try {
+    const site = result.aiReady?.site;
+    if (site) {
+      const fn = viaNest ? "mountAiReady" : "aiReady";
+      const before2 = readFileSync2(site.file, "utf8");
+      const edit2 = replaceAiReadyOptions({ source: before2, file: site.file, line: site.line, callNames: [fn], optionsArg: viaNest ? 1 : 0, config });
+      if ("blocked" in edit2) return edit2;
+      return { plan: { file: site.file, summary: `Replace the ${fn}() options in ${rel(site.file, root)}`, before: before2, after: edit2.after } };
+    }
+    const at = placement(result);
+    if (!at) return { blocked: "couldn't tell which file creates your app" };
+    const before = readFileSync2(at.file, "utf8");
+    const edit = insertAiReadyCall({
+      source: before,
+      file: at.file,
+      code: code.replace(/^import .*\n\n/, ""),
+      importFrom: "@exposify/express",
+      ...at.beforeLine ? { beforeLine: at.beforeLine } : {},
+      ...at.afterLine ? { afterLine: at.afterLine } : {},
+      ...result.createdAt?.file === at.file ? { createdLine: result.createdAt.line } : {}
+    });
+    if ("blocked" in edit) return edit;
+    return { plan: { file: at.file, summary: `Add aiReady() to ${rel(at.file, root)}`, before, after: edit.after } };
+  } catch (err) {
+    return { blocked: err.message };
+  }
+}
+
+// bin/exposify-express.ts
+runCli(process.argv.slice(2), expressAdapter).then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+);