apiforge-analyzer 1.3.1 → 1.3.3

package/README.md

@@ -1,6 +1,6 @@
 # apiforge-analyzer
 
-CLI and library for auto-generating API documentation from live Express, NestJS, Next.js, Vite, and React Router apps.
+CLI and library for auto-generating API documentation from live Express, Fastify, NestJS, Next.js, Vite, and React Router apps.
 
 Routes are extracted at runtime by walking the framework's internal route stack — no static analysis, no decorators, no changes to your production code.
 
@@ -90,6 +90,108 @@ await analyze(app.getHttpServer(), {
 await app.listen(3000)
 ```
 
+### Fastify
+
+Routes are captured via Fastify's `onRoute` hook, so composed paths (`register(fn, { prefix })`,
+relative registrations, nested scopes) resolve to their real runtime URL rather than the literal
+string passed to `app.get(...)`. Handlers are resolved with a TypeScript checker (not a regex),
+so a handler that lives in another module — including one reached through an aliased import,
+a curried factory, or a thin delegating wrapper — is still followed to its real implementation.
+
+```js
+const fastify = require('fastify')
+const { analyze } = require('apiforge-analyzer')
+
+const app = fastify()
+
+app.register(async (v1) => {
+  v1.get('/users', listUsers)
+  v1.post('/users', createUser)
+}, { prefix: '/v1' })
+
+// Call after all routes are registered, before or after app.listen — analyze()
+// awaits app.ready() itself.
+await analyze(app, {
+  projectName: 'My API',
+  apiKey: process.env.APIFORGE_API_KEY,
+  upload: true,
+})
+
+await app.listen({ port: 3000 })
+```
+
+What's inferred automatically, with no annotation: the composed path, the handler's resolved
+source location and leading JSDoc comment (lifted verbatim into `description`), header reads,
+literal and simple-ternary response statuses, and auth — a route counts as authenticated if a
+route-level `onRequest`/`preHandler` hook looks like an auth check by name or body, or if the
+resolved handler calls a guard function (`requireScope`, `requireOperator`, or a local alias of
+either — `const operator = requireOperator` is followed, not missed).
+
+Query and body fields backed by a zod schema — matching both `schema.parse(request.query)` and
+a wrapper call like `parse(schema, request.query)` — come out typed, not as bare field names:
+`z.string().min/max/length()`, `.number()`, `.boolean()`, `.enum([...])` and `.default()` are
+read off the schema and land in the standard `Route.parameters` / `Route.requestBody` fields as
+real JSON Schema (`minLength`/`maxLength`, `enum`, `default`, etc.), the same fields
+`uploadRoutes()` and `exportToJSON()` read — not a side channel that gets dropped on the way out.
+A `.refine()` on the object doesn't drop the fields declared before it.
+
+What can't be inferred safely is reported as `"unknown"` rather than guessed — an unresolved
+handler, or a route-level hook whose name doesn't match a known auth pattern, produces
+`authRequired: "unknown"` instead of a confident `false`.
+
+#### Supplying what can't be inferred
+
+Four extra `AnalyzerOptions` fields cover metadata no static analysis can recover:
+
+```js
+await analyze(app, {
+  projectName: 'My API',
+  apiKey: process.env.APIFORGE_API_KEY,
+
+  // scope name -> extra metadata, joined onto each route's resolved auth scope
+  scopeCatalogPath: './scope-catalog.json',
+
+  // error code -> { status, retry, message, hint? }, joined onto a route by
+  // response status, or by the `errors` list in an annotation (see below)
+  errorCatalogPath: './error-catalog.json',
+
+  // per-prefix response envelope shape — required for every versioned prefix
+  // your API serves once you use this option at all; an unlisted prefix is
+  // reported as a warning rather than silently assumed bare
+  envelopes: {
+    '/v1': { bare: true },
+    '/v2': { wrapper: 'ApiEnvelope', dataField: 'data' },
+  },
+  // With `envelopes` set, `GET /v1/things` and `GET /v2/things` get *different*
+  // `responses['200']` schemas from this one declaration — `/v2`'s nests the same
+  // bare shape under `data` instead of replacing it, so it stays a strict superset.
+
+  // "METHOD /path" -> { summary?, description?, tags?, deprecated?, errors? }
+  // overrides for whatever the analyzer got wrong or couldn't see at all
+  annotationsPath: './annotations.json',
+})
+```
+
+The same per-route overrides can also be attached inline at the route, via Fastify's own
+`config` option — no sidecar file needed for a one-off:
+
+```js
+app.get('/users', {
+  config: {
+    apiforge: { summary: 'List users', tags: ['users'] },
+  },
+}, listUsers)
+```
+
+An `annotationsPath` entry that doesn't match any route Fastify actually registered (a stale
+key left behind after a route was renamed or removed) logs a warning rather than failing
+silently.
+
+We deliberately do **not** read Fastify's request-side `schema` option for documentation —
+adding a schema there gives the route a second, independent validator with its own error
+contract, and `fast-json-stringify` silently drops response fields a *response* schema doesn't
+declare. Use zod (auto-detected) or the annotation options above instead.
+
 ### Microservices — per-service
 
 When running each service independently, pass `service` to tag routes with the service name:
@@ -180,9 +282,23 @@ interface AnalyzerOptions {
 
   skipInProduction?: boolean   // skip when NODE_ENV=production (default: true)
   runOnce?: boolean            // debounce — skip if analyzed within the last 30 s (default: true)
+
+  // Fastify only — see "Supplying what can't be inferred" above
+  scopeCatalogPath?: string
+  errorCatalogPath?: string
+  envelopes?: Record<string, { wrapper: string; dataField: string; excluded?: string[] } | { bare: true }>
+  annotationsPath?: string
 }
 ```
 
+`analyze()` throws instead of resolving to `[]` when the detected or forced framework has no
+analyzer (currently: anything other than `express`, `fastify`, `nestjs`, `nextjs-pages`,
+`nextjs-app`, `vite`, `react-router`). Every other early-exit (no API key, debounced, zero
+routes found, `NODE_ENV=production`) still resolves to `[]` — only "this framework cannot be
+analyzed" is a thrown error, so a caller can tell the two apart. `detectFramework()` also
+exposes this directly: `detectFramework(app).supported` is `false` for a framework it can
+name but not analyze (currently `koa`, `hapi`, `unknown`).
+
 ## Architecture detection
 
 The CLI scores structural signals to pick the right architecture automatically:
@@ -216,11 +332,57 @@ Each collected route:
   requestBodyFields: [],
   responseStatuses: [200, 404],
   framework: 'express',
-  moduleName?: 'users',        // modular-monolithic only
-  serviceName?: 'auth-service' // microservices only
+  module?: 'users',        // modular-monolithic only
+  service?: 'auth-service' // microservices only
 }
 ```
 
+## Escape hatch — building routes yourself
+
+If your framework has no `analyze*()` function, call `uploadRoutes()` directly with a
+hand-built `Route[]`. This is the same function every `analyze*()` call ends up using
+internally — it's a supported, typed, top-level export, not a private helper.
+
+```ts
+import { uploadRoutes, type Route } from 'apiforge-analyzer'
+
+const routes: Route[] = [
+  {
+    method: 'GET',
+    path: '/api/users/:id',
+    tag: 'users',
+    operationId: 'get_api_users_id',
+    summary: 'Get a user by id',
+    middleware: [],
+    authRequired: true,
+    pathParams: ['id'],
+    queryParams: [],
+    requestBodyFields: [],
+    linkedPaths: [],
+    hasAuth: true,
+    framework: 'my-framework',
+    // routeKey?: stable dedup key the dashboard uses across uploads — see below
+  },
+]
+
+await uploadRoutes(routes, {
+  projectName: 'My API',
+  apiKey: process.env.APIFORGE_API_KEY!,
+})
+```
+
+The fields above (`method`, `path`, `tag`, `operationId`, `summary`, `middleware`,
+`authRequired`, `pathParams`, `queryParams`, `requestBodyFields`, `linkedPaths`, `hasAuth`,
+`framework`) are the only ones `Route` requires; everything else (`description`, `tags`,
+`headerParams`, `responseStatuses`, `parameters`, `requestBody`, `responses`, `module`,
+`service`, ...) is optional and gets a reasonable default from `enrichRoutes()`.
+
+**Set `routeKey` yourself.** If you don't, it defaults to `api-001`, `api-002`, ... based on
+array position — which shifts if a route is added, removed, or reordered between uploads, so
+the dashboard can no longer tell "this is the same endpoint as last time" from "this is a new
+one". Use something stable per endpoint, e.g. `` `${method} ${path}` ``, as every built-in
+analyzer does.
+
 ## ESM and CommonJS
 
 ```js

package/dist/cjs/cli.js

@@ -27,7 +27,7 @@ const green = (s) => `${gn}${s}${r}`;
 const yellow = (s) => `${yl}${s}${r}`;
 const red = (s) => `${rd}${s}${r}`;
 const white = (s) => `${wh}${s}${r}`;
-const VERSION = '1.3.1';
+const VERSION = '1.3.2';
 // Built-in URLs — users never need to configure these
 const BACKEND_PROD = 'https://apiforgeapi.brainfogagency.com';
 const DASHBOARD_PROD = 'https://apiforge.brainfogagency.com/dashboard';
@@ -224,11 +224,18 @@ async function main() {
     if (serverResult.status === 'error') {
         s.stop(red(`✗ ${serverResult.message}`));
         // Give a targeted hint for common failure modes
-        if (serverResult.message.includes('API key')) {
-            prompts_1.log.warn(yellow('Hint: The CLI wrote your key to .env.local — but your server may not load it.'));
-            prompts_1.log.warn(yellow('      Add this at the top of your entry file before calling analyze():'));
-            prompts_1.log.info(`      ${cyan("require('dotenv').config({ path: '.env.local' })")}`);
-            prompts_1.log.warn(yellow('      Or install dotenv:  npm install dotenv'));
+        if (serverResult.message.includes('API key') || serverResult.message.includes('Invalid API key')) {
+            prompts_1.log.warn(yellow('Hint: Your API key was rejected by the server. Common causes:'));
+            prompts_1.log.warn(yellow(''));
+            prompts_1.log.warn(yellow('  1. Key not yet created — go to your dashboard and generate one:'));
+            prompts_1.log.info(`     ${cyan('https://apiforge.brainfogagency.com/dashboard')}`);
+            prompts_1.log.warn(yellow(''));
+            prompts_1.log.warn(yellow('  2. Key belongs to a different account — make sure you\'re logged in'));
+            prompts_1.log.warn(yellow('     to the same account that owns this project.'));
+            prompts_1.log.warn(yellow(''));
+            prompts_1.log.warn(yellow('  3. Server not loading .env.local — add this at the top of your entry file:'));
+            prompts_1.log.info(`     ${cyan("require('dotenv').config({ path: '.env.local' })")}`);
+            prompts_1.log.warn(yellow('     Or install dotenv:  npm install dotenv'));
         }
         else if (serverResult.message.includes('No routes')) {
             prompts_1.log.warn(yellow('Hint: Make sure all routes are registered before analyze() is called.'));
@@ -238,6 +245,14 @@ async function main() {
             prompts_1.log.warn(yellow('Hint: Your server might be taking too long to start, or the analyzer'));
             prompts_1.log.warn(yellow('      is not being called. Check your server logs for APIForge messages.'));
         }
+        // Show captured server output to help debug the root cause
+        const capturedOutput = serverResult.serverOutput;
+        if (capturedOutput) {
+            prompts_1.log.info('');
+            prompts_1.log.info(dim('─── Server output ───────────────────────────────'));
+            capturedOutput.split('\n').slice(0, 25).forEach((line) => prompts_1.log.info(dim(`  ${line}`)));
+            prompts_1.log.info(dim('─────────────────────────────────────────────────'));
+        }
         await offerCleanup(entryFile, injected);
         (0, prompts_1.outro)(red('Analysis failed.'));
         process.exit(1);
@@ -395,6 +410,158 @@ function hasDockerCompose(cwd) {
     return ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml']
         .some(f => (0, fs_1.existsSync)((0, path_1.join)(cwd, f)));
 }
+/**
+ * Find the gateway among the discovered services (by name or by proxy-middleware
+ * usage) and parse its prefix → service map, e.g. { auth: '/auth', gold_rates: '/gold-rates' }.
+ * Matches the common `'/prefix': process.env.X_SERVICE_URL || ...` gateway route-table
+ * pattern (express-gateway / http-proxy-middleware style). Returns {} if no gateway
+ * or no recognizable mapping is found — callers should treat that as "no rewrite."
+ */
+function detectGatewayPrefixMap(cwd, services) {
+    const prefixMap = {};
+    for (const svc of services) {
+        const svcDir = svc.dir.replace(/^\.\//, '');
+        const relEntry = svc.entryFile ?? findEntryInDir((0, path_1.join)(cwd, svcDir));
+        if (!relEntry)
+            continue;
+        let source = '';
+        try {
+            source = (0, fs_1.readFileSync)((0, path_1.join)(cwd, svcDir, relEntry), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const looksLikeGateway = /gateway/i.test(svc.name) || /createProxyMiddleware|http-proxy-middleware/.test(source);
+        if (!looksLikeGateway)
+            continue;
+        // '/auth': process.env.AUTH_SERVICE_URL || `http://...`
+        const re = /['"](\/[a-zA-Z0-9_-]*)['"]\s*:\s*process\.env\.([A-Z][A-Z0-9_]*)/g;
+        let m;
+        while ((m = re.exec(source))) {
+            const prefix = m[1];
+            const serviceName = m[2].replace(/_SERVICE_URL$|_URL$/, '').toLowerCase();
+            if (!prefixMap[serviceName])
+                prefixMap[serviceName] = prefix; // first (primary) mount wins over aliases
+        }
+        if (Object.keys(prefixMap).length > 0)
+            break;
+    }
+    return prefixMap;
+}
+function withGatewayPrefix(prefix, routePath) {
+    if (routePath === '/')
+        return prefix;
+    return prefix.replace(/\/$/, '') + (routePath.startsWith('/') ? routePath : `/${routePath}`);
+}
+// ─── Postman collection enrichment ─────────────────────────────────────────────
+// Runtime introspection only sees field NAMES (via regex over handler source),
+// never real example values — a Postman collection, when present, already has
+// hand-written example bodies and descriptions. We fold those in as enrichment
+// only: matched by method + path, never adds or removes an endpoint.
+function findFileRecursive(dir, matches, maxDepth, depth = 0) {
+    if (depth > maxDepth)
+        return null;
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const e of entries) {
+        if (e.isFile() && matches(e.name))
+            return (0, path_1.join)(dir, e.name);
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && !['node_modules', '.git', 'dist', 'build', '.next'].includes(e.name)) {
+            const found = findFileRecursive((0, path_1.join)(dir, e.name), matches, maxDepth, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+function findPostmanCollection(cwd) {
+    const isCollection = (name) => name.endsWith('.postman_collection.json');
+    for (const dir of ['postman', 'docs/postman', '.postman', 'collections']) {
+        const dirPath = (0, path_1.join)(cwd, dir);
+        if (!(0, fs_1.existsSync)(dirPath))
+            continue;
+        try {
+            const match = (0, fs_1.readdirSync)(dirPath).find(isCollection);
+            if (match)
+                return (0, path_1.join)(dirPath, match);
+        }
+        catch { }
+    }
+    return findFileRecursive(cwd, isCollection, 3);
+}
+/** "{{baseUrl}}/gold-rates/graph/{{userId}}?interval=x" -> "/gold-rates/graph/:userId" */
+function postmanRawToRoutePath(raw) {
+    let p = raw.trim();
+    p = p.replace(/^\{\{[^}]+\}\}/, '');
+    p = p.split('?')[0];
+    p = p.replace(/\{\{([a-zA-Z0-9_]+)\}\}/g, ':$1');
+    if (!p)
+        p = '/';
+    if (!p.startsWith('/'))
+        p = '/' + p;
+    if (p !== '/' && p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p;
+}
+/** Recursively walk a Postman collection's item tree (folders nest via `item`; requests carry `request`). */
+function walkPostmanItems(items, index) {
+    for (const node of items ?? []) {
+        if (Array.isArray(node.item))
+            walkPostmanItems(node.item, index);
+        if (!node.request)
+            continue;
+        const req = node.request;
+        const method = String(req.method || 'GET').toUpperCase();
+        const rawUrl = typeof req.url === 'string' ? req.url : req.url?.raw;
+        if (!rawUrl)
+            continue;
+        const key = `${method} ${postmanRawToRoutePath(rawUrl)}`;
+        if (index.has(key))
+            continue; // first match wins — collection often repeats the same endpoint in a smoke-test folder
+        const entry = {};
+        if (req.body?.mode === 'raw' && typeof req.body.raw === 'string' && req.body.raw.trim()) {
+            entry.bodyExample = req.body.raw.trim();
+        }
+        if (typeof req.description === 'string' && req.description.trim()) {
+            entry.description = req.description.trim();
+        }
+        if (entry.bodyExample || entry.description)
+            index.set(key, entry);
+    }
+}
+/** Enrich collected routes in-place with Postman example bodies/descriptions, matched by method+path. Never adds or drops routes. */
+function enrichRoutesFromPostman(cwd, routes) {
+    const collectionPath = findPostmanCollection(cwd);
+    if (!collectionPath)
+        return;
+    try {
+        const collection = JSON.parse((0, fs_1.readFileSync)(collectionPath, 'utf-8'));
+        const index = new Map();
+        walkPostmanItems(collection.item, index);
+        let enriched = 0;
+        for (const route of routes) {
+            const match = index.get(`${route.method} ${route.path}`);
+            if (!match)
+                continue;
+            if (match.bodyExample)
+                route.bodyExample = match.bodyExample;
+            if (match.description && !route.description)
+                route.description = match.description;
+            enriched++;
+        }
+        if (enriched > 0) {
+            prompts_1.log.info(dim(`Enriched ${enriched} routes with examples from ${(0, path_1.basename)(collectionPath)}`));
+        }
+    }
+    catch { }
+}
 async function microservicesFlow(config, opts) {
     const cwd = process.cwd();
     const allRoutes = [];
@@ -437,6 +604,14 @@ async function microservicesFlow(config, opts) {
         '',
         dim('Each service is started individually and its routes are collected.'),
     ].join('\n'), 'Multi-service analysis');
+    // Routes are collected at each service's own internal paths (e.g. auth's /register),
+    // not the path clients actually call through the gateway (/auth/register) — Express
+    // strips the mount prefix before the service ever sees the request. Rewrite paths
+    // here so the docs match what's actually callable.
+    const gatewayPrefixes = detectGatewayPrefixMap(cwd, config.services);
+    if (Object.keys(gatewayPrefixes).length > 0) {
+        prompts_1.log.info(dim(`Gateway prefixes detected: ${Object.entries(gatewayPrefixes).map(([s, p]) => `${s}→${p}`).join(', ')}`));
+    }
     for (const svc of config.services) {
         const svcSpin = (0, prompts_1.spinner)();
         svcSpin.start(`${bold(svc.name)} — starting…`);
@@ -465,13 +640,14 @@ async function microservicesFlow(config, opts) {
             detached: false,
         });
         // Capture output so failures are debuggable without re-running the service by hand.
-        // Bounded to the last ~4000 chars so a chatty/looping service can't blow up memory.
+        // Keep the HEAD, not the tail: Node prints "Error: ..." / "Cannot find module ..."
+        // first, then unwinds the call stack — a long stack trace must not push that
+        // opening line out of the window, so stop growing once capped instead of sliding.
         let output = '';
-        const MAX_OUTPUT = 4000;
+        const MAX_OUTPUT = 6000;
         const capture = (chunk) => {
-            output += chunk.toString();
-            if (output.length > MAX_OUTPUT)
-                output = output.slice(-MAX_OUTPUT);
+            if (output.length < MAX_OUTPUT)
+                output += chunk.toString();
         };
         child.stdout?.on('data', capture);
         child.stderr?.on('data', capture);
@@ -484,7 +660,12 @@ async function microservicesFlow(config, opts) {
         catch { }
         tryUnlink((0, path_1.join)(cwd, statusFile));
         if (routes && routes.length > 0) {
-            const annotated = routes.map((r) => ({ ...r, service: svc.name }));
+            const prefix = gatewayPrefixes[svc.name];
+            const annotated = routes.map((r) => ({
+                ...r,
+                service: svc.name,
+                path: prefix ? withGatewayPrefix(prefix, r.path) : r.path,
+            }));
             allRoutes.push(...annotated);
             serviceMeta.push({ name: svc.name, baseUrl: svc.baseUrl });
             svcSpin.stop(green(`✓ ${svc.name} — ${routes.length} routes collected`));
@@ -493,7 +674,7 @@ async function microservicesFlow(config, opts) {
             svcSpin.stop(yellow(`◌ ${svc.name} — no routes collected (timeout or error)`));
             const trimmed = output.trim();
             if (trimmed) {
-                prompts_1.log.error(dim(`   ${bold(svc.name)} output:\n` + trimmed.split('\n').slice(-20).map(l => `   ${l}`).join('\n')));
+                prompts_1.log.error(dim(`   ${bold(svc.name)} output:\n` + trimmed.split('\n').slice(0, 30).map(l => `   ${l}`).join('\n')));
             }
         }
         // Remove injected code
@@ -503,6 +684,7 @@ async function microservicesFlow(config, opts) {
     // Safety: clean up any remaining injections (e.g. if process was interrupted)
     for (const f of injectedFiles)
         removeInjectedCode(f);
+    enrichRoutesFromPostman(cwd, allRoutes);
     if (allRoutes.length === 0) {
         prompts_1.log.error(red('No routes were collected from any service.'));
         (0, prompts_1.outro)(red('Analysis failed.'));
@@ -582,11 +764,20 @@ function startAndWaitForAnalysis(command, timeoutMs) {
         const statusPath = (0, path_1.join)(process.cwd(), STATUS_FILE);
         const child = (0, child_process_1.spawn)(command, {
             cwd: process.cwd(),
-            stdio: 'ignore',
+            stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
             env: { ...process.env },
             detached: false,
         });
+        // Capture server output (head-capped) so we can show it on failure
+        let serverOutput = '';
+        const MAX_OUTPUT = 4000;
+        const captureOutput = (chunk) => {
+            if (serverOutput.length < MAX_OUTPUT)
+                serverOutput += chunk.toString();
+        };
+        child.stdout?.on('data', captureOutput);
+        child.stderr?.on('data', captureOutput);
         let resolved = false;
         function finish(result) {
             if (resolved)
@@ -598,7 +789,7 @@ function startAndWaitForAnalysis(command, timeoutMs) {
                 child.kill('SIGTERM');
             }
             catch { }
-            resolve(result);
+            resolve({ ...result, serverOutput: serverOutput.trim() });
         }
         // Poll for the status file every 500 ms
         const poller = setInterval(() => {
@@ -1023,13 +1214,33 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
             `    upload: true,`,
             `    runOnce: true,`,
         ].join('\n');
+    // Collection mode: some services only mount routes inside an async bootstrap
+    // gated behind a DB/broker connect (which may hang/fail outside Docker).
+    // Poll briefly for app._router to be populated (Express-shaped apps only)
+    // before giving up and collecting whatever is there — bounded well under
+    // the CLI's 30s per-service timeout so a hung connect still surfaces.
+    const runAnalyze = `APIForge.analyze(${appVar}, {\n${opts}\n  })`;
+    const call = collectionOpts
+        ? [
+            `  let __apiforgeTries = 0`,
+            `  const __apiforgeTryCollect = () => {`,
+            `    const hasRoutes = !${appVar} || !${appVar}._router`,
+            `      ? true`,
+            `      : Array.isArray(${appVar}._router.stack) && ${appVar}._router.stack.length > 0`,
+            `    if (hasRoutes || __apiforgeTries++ >= 26) {`,
+            `      ${runAnalyze}`,
+            `    } else {`,
+            `      setTimeout(__apiforgeTryCollect, 300)`,
+            `    }`,
+            `  }`,
+            `  __apiforgeTryCollect()`,
+        ].join('\n')
+        : `  ${runAnalyze}`;
     if (isESM) {
         return [
             `// APIForge — https://apiforge.brainfogagency.com`,
             `import('apiforge-analyzer').then(({ default: APIForge }) => {`,
-            `  APIForge.analyze(${appVar}, {`,
-            opts,
-            `  })`,
+            call,
             `}).catch(() => {})`,
             '',
         ].join('\n');
@@ -1038,9 +1249,7 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
         `// APIForge — https://apiforge.brainfogagency.com`,
         `Promise.resolve().then(() => require('apiforge-analyzer')).then(mod => {`,
         `  const APIForge = mod.default || mod`,
-        `  APIForge.analyze(${appVar}, {`,
-        opts,
-        `  })`,
+        call,
         `}).catch(() => {})`,
         '',
     ].join('\n');
@@ -1064,6 +1273,12 @@ function detectAppVariable(content) {
         /(?:const|let|var)\s+(\w+)\s*=\s*(?:fastify|Fastify)\s*\(/,
         /(?:const|let|var)\s+(\w+)\s*=\s*new\s+Koa\s*\(/,
         /(?:const|let|var)\s+(\w+)\s*=\s*(?:Router|createApp|createServer)\s*\(/,
+        // Inline `require('fastify')(...)` / `require('express')(...)` — the app
+        // factory is never bound to a local name, only its return value is. This
+        // is at least as common as the named-import style above (it's the pattern
+        // in Fastify's own project generator output), and the patterns above never
+        // match it because there's no `fastify`/`express` identifier in the source.
+        /(?:const|let|var)\s+(\w+)\s*=\s*require\s*\(\s*['"](?:fastify|express)['"]\s*\)\s*(?:\.default\s*)?\(/,
     ];
     for (const re of patterns) {
         const m = content.match(re);

package/dist/cjs/detect.js

@@ -1,8 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_FRAMEWORKS = void 0;
 exports.detectFramework = detectFramework;
 const fs_1 = require("fs");
 const path_1 = require("path");
+/**
+ * Frameworks analyze() can actually dispatch to. Detection can identify more
+ * frameworks than this (koa, hapi) — those are named so the detector is honest
+ * about what it saw, but `supported: false` tells callers not to expect output.
+ */
+exports.SUPPORTED_FRAMEWORKS = new Set([
+    'express',
+    'fastify',
+    'nestjs',
+    'nextjs-pages',
+    'nextjs-app',
+    'vite',
+    'react-router',
+]);
 const cwd = () => process.cwd();
 function fileExists(rel) {
     return (0, fs_1.existsSync)((0, path_1.join)(cwd(), rel));
@@ -21,16 +36,19 @@ function tryResolve(mod) {
  * Detect the web framework from the live app instance + filesystem hints.
  * Confidence is used to pick the best match when multiple signals fire.
  */
+function mk(name, confidence) {
+    return { name, confidence, supported: exports.SUPPORTED_FRAMEWORKS.has(name) };
+}
 function detectFramework(app) {
     // ── Instance-based detection (highest confidence) ─────────────────────────
     if (app && typeof app === 'function') {
         // Express: _router or lazyrouter
         if (app._router || (app.lazyrouter && typeof app.lazyrouter === 'function')) {
-            return { name: 'express', confidence: 1.0 };
+            return mk('express', 1.0);
         }
         // Koa: middleware array
         if (Array.isArray(app.middleware) && typeof app.use === 'function' && app.context) {
-            return { name: 'koa', confidence: 0.95 };
+            return mk('koa', 0.95);
         }
     }
     // Fastify: inject method and route method
@@ -38,7 +56,7 @@ function detectFramework(app) {
         typeof app === 'object' &&
         typeof app.inject === 'function' &&
         typeof app.route === 'function') {
-        return { name: 'fastify', confidence: 1.0 };
+        return mk('fastify', 1.0);
     }
     // Hapi: server with route + start methods
     if (app &&
@@ -46,43 +64,43 @@ function detectFramework(app) {
         typeof app.route === 'function' &&
         typeof app.start === 'function' &&
         typeof app.stop === 'function') {
-        return { name: 'hapi', confidence: 0.95 };
+        return mk('hapi', 0.95);
     }
     // NestJS application
     if (app &&
         typeof app === 'object' &&
         typeof app.getHttpServer === 'function' &&
         typeof app.listen === 'function') {
-        return { name: 'nestjs', confidence: 0.95 };
+        return mk('nestjs', 0.95);
     }
     // ── Filesystem detection ──────────────────────────────────────────────────
     // Next.js App Router
     if (fileExists('app') && (fileExists('app/layout.tsx') || fileExists('app/layout.js'))) {
-        return { name: 'nextjs-app', confidence: 0.92 };
+        return mk('nextjs-app', 0.92);
     }
     // Next.js Pages Router
     if (fileExists('pages/api') || fileExists('src/pages/api')) {
-        return { name: 'nextjs-pages', confidence: 0.90 };
+        return mk('nextjs-pages', 0.90);
     }
     if (fileExists('next.config.js') ||
         fileExists('next.config.mjs') ||
         fileExists('next.config.ts')) {
-        return { name: 'nextjs-pages', confidence: 0.75 };
+        return mk('nextjs-pages', 0.75);
     }
     // ── Dependency-based detection (lowest confidence) ────────────────────────
     if (tryResolve('express'))
-        return { name: 'express', confidence: 0.70 };
+        return mk('express', 0.70);
     if (tryResolve('fastify'))
-        return { name: 'fastify', confidence: 0.70 };
+        return mk('fastify', 0.70);
     if (tryResolve('koa'))
-        return { name: 'koa', confidence: 0.70 };
+        return mk('koa', 0.70);
     if (tryResolve('@hapi/hapi') || tryResolve('hapi'))
-        return { name: 'hapi', confidence: 0.70 };
+        return mk('hapi', 0.70);
     if (tryResolve('@nestjs/core'))
-        return { name: 'nestjs', confidence: 0.70 };
+        return mk('nestjs', 0.70);
     if (tryResolve('vite'))
-        return { name: 'vite', confidence: 0.60 };
+        return mk('vite', 0.60);
     if (tryResolve('react-router-dom'))
-        return { name: 'react-router', confidence: 0.55 };
-    return { name: 'unknown', confidence: 0 };
+        return mk('react-router', 0.55);
+    return mk('unknown', 0);
 }