apiforge-analyzer 1.3.0 → 1.3.2

package/dist/cjs/arch-detect.js

@@ -44,6 +44,27 @@ function detectArchitectureType(rootDir) {
         siblingPackages.forEach(p => servicePaths.push(p));
         evidence.push(`${siblingPackages.length} sibling package.json files (${siblingPackages.join(', ')})`);
     }
+    // services/, apps/, or microservices/ dir containing 2+ independently-built
+    // subdirs (own Dockerfile and/or package.json) — the common Docker-Compose
+    // microservices layout, where each service lives one level deeper than the
+    // sibling-package check above looks.
+    for (const parentDir of ['services', 'apps', 'microservices']) {
+        const parentPath = (0, path_1.join)(rootDir, parentDir);
+        if (!(0, fs_1.existsSync)(parentPath))
+            continue;
+        try {
+            const subdirs = (0, fs_1.readdirSync)(parentPath, { withFileTypes: true }).filter(d => d.isDirectory());
+            const ownedServices = subdirs.filter(d => (0, fs_1.existsSync)((0, path_1.join)(parentPath, d.name, 'Dockerfile')) ||
+                (0, fs_1.existsSync)((0, path_1.join)(parentPath, d.name, 'package.json')));
+            if (ownedServices.length >= 2) {
+                microScore += 45;
+                ownedServices.forEach(d => servicePaths.push(`./${parentDir}/${d.name}`));
+                evidence.push(`${parentDir}/ has ${ownedServices.length} independently-built services: ${ownedServices.map(d => d.name).join(', ')}`);
+                break;
+            }
+        }
+        catch { }
+    }
     // ── Modular Monolithic signals ────────────────────────────────────────────────
     // NestJS module files anywhere in src/
     const srcDir = (0, path_1.join)(rootDir, 'src');

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.0';
+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';
@@ -391,6 +391,162 @@ function waitForServiceStatusFile(statusFile, timeoutMs) {
         }, timeoutMs);
     });
 }
+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 = [];
@@ -403,6 +559,29 @@ async function microservicesFlow(config, opts) {
     tryUnlink((0, path_1.join)(cwd, STATUS_FILE));
     tryUnlink((0, path_1.join)(cwd, LOCK_FILE));
     persistApiKeyToEnv(opts.apiKey);
+    if (hasDockerCompose(cwd)) {
+        (0, prompts_1.note)([
+            `${yellow('Docker Compose detected — APIForge will NOT start, build, or touch Docker.')}`,
+            '',
+            dim('Each service below is run directly with node/tsx on this machine, just'),
+            dim('long enough to capture its routes, then reverted. Your containers (if'),
+            dim('running) are left completely alone — no ports, network, or images are used.'),
+            '',
+            bold('For this to work:'),
+            `  ${dim('·')} ${bold('npm install')} ${dim('has been run at the project root (deps must resolve outside Docker)')}`,
+            `  ${dim('·')} a readable ${bold('.env')} ${dim('at the project root (same values Docker passes via env_file)')}`,
+            '',
+            dim("Routes are captured before RabbitMQ/Redis/DB connections resolve, so those don't need to be reachable."),
+        ].join('\n'), 'Docker Compose project');
+        const proceed = await (0, prompts_1.confirm)({
+            message: 'Run services locally to collect routes?',
+            initialValue: true,
+        });
+        if ((0, prompts_1.isCancel)(proceed) || !proceed) {
+            (0, prompts_1.cancel)(dim('Cancelled. Run `npm install` at the project root, then re-run apiforge.'));
+            process.exit(0);
+        }
+    }
     (0, prompts_1.note)([
         bold(`Analyzing ${config.services.length} service${config.services.length > 1 ? 's' : ''}…`),
         '',
@@ -410,6 +589,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…`);
@@ -432,11 +619,23 @@ async function microservicesFlow(config, opts) {
         const startCmd = svc.startCommand ?? serviceNodeCommand(fullEntry);
         const child = (0, child_process_1.spawn)(startCmd, {
             cwd,
-            stdio: 'ignore',
+            stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
             env: { ...process.env },
             detached: false,
         });
+        // Capture output so failures are debuggable without re-running the service by hand.
+        // 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 = 6000;
+        const capture = (chunk) => {
+            if (output.length < MAX_OUTPUT)
+                output += chunk.toString();
+        };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
         // Wait up to 30 s for the status file to appear
         const routes = await waitForServiceStatusFile(statusFile, 30000);
         // Kill service process
@@ -446,13 +645,22 @@ 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`));
         }
         else {
             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(0, 30).map(l => `   ${l}`).join('\n')));
+            }
         }
         // Remove injected code
         removeInjectedCode(fullEntry);
@@ -461,6 +669,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.'));
@@ -896,8 +1105,15 @@ function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl, architec
     const isESM = detectESM(filePath, content);
     const appVar = detectAppVariable(content) ?? 'app';
     const snippet = buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, architectureType, collectionOpts);
+    // Collection mode (microservices): append at end of file instead of before
+    // .listen(). Route mounting (app.use(...)) happens synchronously at module
+    // load; .listen() is often gated behind an async bootstrap (DB/broker
+    // connect) that can hang or fail outside its container/network. Appending
+    // at the end runs right after the synchronous portion of the module —
+    // independent of whether that bootstrap ever finishes — so route capture
+    // doesn't require RabbitMQ/Redis/DB to be reachable.
     const listenRe = /\b(?:app|server|httpServer|http)\s*\.listen\s*\(/;
-    const listenMatch = listenRe.exec(content);
+    const listenMatch = collectionOpts ? undefined : listenRe.exec(content);
     let newContent;
     let injectionPoint;
     if (listenMatch?.index !== undefined) {
@@ -974,13 +1190,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');
@@ -989,9 +1225,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');

package/dist/esm/arch-detect.js

@@ -41,6 +41,27 @@ export function detectArchitectureType(rootDir) {
         siblingPackages.forEach(p => servicePaths.push(p));
         evidence.push(`${siblingPackages.length} sibling package.json files (${siblingPackages.join(', ')})`);
     }
+    // services/, apps/, or microservices/ dir containing 2+ independently-built
+    // subdirs (own Dockerfile and/or package.json) — the common Docker-Compose
+    // microservices layout, where each service lives one level deeper than the
+    // sibling-package check above looks.
+    for (const parentDir of ['services', 'apps', 'microservices']) {
+        const parentPath = join(rootDir, parentDir);
+        if (!existsSync(parentPath))
+            continue;
+        try {
+            const subdirs = readdirSync(parentPath, { withFileTypes: true }).filter(d => d.isDirectory());
+            const ownedServices = subdirs.filter(d => existsSync(join(parentPath, d.name, 'Dockerfile')) ||
+                existsSync(join(parentPath, d.name, 'package.json')));
+            if (ownedServices.length >= 2) {
+                microScore += 45;
+                ownedServices.forEach(d => servicePaths.push(`./${parentDir}/${d.name}`));
+                evidence.push(`${parentDir}/ has ${ownedServices.length} independently-built services: ${ownedServices.map(d => d.name).join(', ')}`);
+                break;
+            }
+        }
+        catch { }
+    }
     // ── Modular Monolithic signals ────────────────────────────────────────────────
     // NestJS module files anywhere in src/
     const srcDir = join(rootDir, 'src');

package/dist/esm/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { group, intro, outro, text, select, password, confirm, tasks, note, log, isCancel, cancel, spinner, } from '@clack/prompts';
 import { readFileSync, existsSync, writeFileSync, unlinkSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { join, basename } from 'path';
 import { spawn } from 'child_process';
 import axios from 'axios';
 import { detectArchitectureType } from './arch-detect.js';
@@ -22,7 +22,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.0';
+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';
@@ -386,6 +386,162 @@ function waitForServiceStatusFile(statusFile, timeoutMs) {
         }, timeoutMs);
     });
 }
+function hasDockerCompose(cwd) {
+    return ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml']
+        .some(f => existsSync(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(join(cwd, svcDir));
+        if (!relEntry)
+            continue;
+        let source = '';
+        try {
+            source = readFileSync(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 = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const e of entries) {
+        if (e.isFile() && matches(e.name))
+            return join(dir, e.name);
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && !['node_modules', '.git', 'dist', 'build', '.next'].includes(e.name)) {
+            const found = findFileRecursive(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 = join(cwd, dir);
+        if (!existsSync(dirPath))
+            continue;
+        try {
+            const match = readdirSync(dirPath).find(isCollection);
+            if (match)
+                return 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(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) {
+            log.info(dim(`Enriched ${enriched} routes with examples from ${basename(collectionPath)}`));
+        }
+    }
+    catch { }
+}
 async function microservicesFlow(config, opts) {
     const cwd = process.cwd();
     const allRoutes = [];
@@ -398,6 +554,29 @@ async function microservicesFlow(config, opts) {
     tryUnlink(join(cwd, STATUS_FILE));
     tryUnlink(join(cwd, LOCK_FILE));
     persistApiKeyToEnv(opts.apiKey);
+    if (hasDockerCompose(cwd)) {
+        note([
+            `${yellow('Docker Compose detected — APIForge will NOT start, build, or touch Docker.')}`,
+            '',
+            dim('Each service below is run directly with node/tsx on this machine, just'),
+            dim('long enough to capture its routes, then reverted. Your containers (if'),
+            dim('running) are left completely alone — no ports, network, or images are used.'),
+            '',
+            bold('For this to work:'),
+            `  ${dim('·')} ${bold('npm install')} ${dim('has been run at the project root (deps must resolve outside Docker)')}`,
+            `  ${dim('·')} a readable ${bold('.env')} ${dim('at the project root (same values Docker passes via env_file)')}`,
+            '',
+            dim("Routes are captured before RabbitMQ/Redis/DB connections resolve, so those don't need to be reachable."),
+        ].join('\n'), 'Docker Compose project');
+        const proceed = await confirm({
+            message: 'Run services locally to collect routes?',
+            initialValue: true,
+        });
+        if (isCancel(proceed) || !proceed) {
+            cancel(dim('Cancelled. Run `npm install` at the project root, then re-run apiforge.'));
+            process.exit(0);
+        }
+    }
     note([
         bold(`Analyzing ${config.services.length} service${config.services.length > 1 ? 's' : ''}…`),
         '',
@@ -405,6 +584,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) {
+        log.info(dim(`Gateway prefixes detected: ${Object.entries(gatewayPrefixes).map(([s, p]) => `${s}→${p}`).join(', ')}`));
+    }
     for (const svc of config.services) {
         const svcSpin = spinner();
         svcSpin.start(`${bold(svc.name)} — starting…`);
@@ -427,11 +614,23 @@ async function microservicesFlow(config, opts) {
         const startCmd = svc.startCommand ?? serviceNodeCommand(fullEntry);
         const child = spawn(startCmd, {
             cwd,
-            stdio: 'ignore',
+            stdio: ['ignore', 'pipe', 'pipe'],
             shell: true,
             env: { ...process.env },
             detached: false,
         });
+        // Capture output so failures are debuggable without re-running the service by hand.
+        // 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 = 6000;
+        const capture = (chunk) => {
+            if (output.length < MAX_OUTPUT)
+                output += chunk.toString();
+        };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
         // Wait up to 30 s for the status file to appear
         const routes = await waitForServiceStatusFile(statusFile, 30000);
         // Kill service process
@@ -441,13 +640,22 @@ async function microservicesFlow(config, opts) {
         catch { }
         tryUnlink(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`));
         }
         else {
             svcSpin.stop(yellow(`◌ ${svc.name} — no routes collected (timeout or error)`));
+            const trimmed = output.trim();
+            if (trimmed) {
+                log.error(dim(`   ${bold(svc.name)} output:\n` + trimmed.split('\n').slice(0, 30).map(l => `   ${l}`).join('\n')));
+            }
         }
         // Remove injected code
         removeInjectedCode(fullEntry);
@@ -456,6 +664,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) {
         log.error(red('No routes were collected from any service.'));
         outro(red('Analysis failed.'));
@@ -891,8 +1100,15 @@ function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl, architec
     const isESM = detectESM(filePath, content);
     const appVar = detectAppVariable(content) ?? 'app';
     const snippet = buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, architectureType, collectionOpts);
+    // Collection mode (microservices): append at end of file instead of before
+    // .listen(). Route mounting (app.use(...)) happens synchronously at module
+    // load; .listen() is often gated behind an async bootstrap (DB/broker
+    // connect) that can hang or fail outside its container/network. Appending
+    // at the end runs right after the synchronous portion of the module —
+    // independent of whether that bootstrap ever finishes — so route capture
+    // doesn't require RabbitMQ/Redis/DB to be reachable.
     const listenRe = /\b(?:app|server|httpServer|http)\s*\.listen\s*\(/;
-    const listenMatch = listenRe.exec(content);
+    const listenMatch = collectionOpts ? undefined : listenRe.exec(content);
     let newContent;
     let injectionPoint;
     if (listenMatch?.index !== undefined) {
@@ -969,13 +1185,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');
@@ -984,9 +1220,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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiforge-analyzer",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Universal API documentation generator for Express, Next.js, Vite, React Router, and Node.js",
   "type": "module",
   "main": "./dist/cjs/index.js",