apiforge-analyzer 1.2.1 → 1.3.1

package/dist/esm/cli.js

@@ -1,9 +1,11 @@
 #!/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 } from 'fs';
+import { readFileSync, existsSync, writeFileSync, unlinkSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { spawn } from 'child_process';
 import axios from 'axios';
+import { detectArchitectureType } from './arch-detect.js';
+import { uploadRoutes } from './uploader.js';
 // ─── ANSI colour helpers ──────────────────────────────────────────────────────
 const r = '\x1b[0m';
 const b = '\x1b[1m';
@@ -20,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.2.0';
+const VERSION = '1.3.1';
 // Built-in URLs — users never need to configure these
 const BACKEND_PROD = 'https://apiforgeapi.brainfogagency.com';
 const DASHBOARD_PROD = 'https://apiforge.brainfogagency.com/dashboard';
@@ -80,25 +82,6 @@ async function main() {
     if (isCancel(answers))
         process.exit(0);
     const { projectName, apiKey, baseUrl } = answers;
-    // ── Select run command ────────────────────────────────────────────────────
-    const scripts = detectScripts();
-    const scriptOptions = scripts.map(s => ({
-        value: s.command,
-        label: `${bold(s.name)}  ${dim('→')}  ${dim(s.command)}`,
-    }));
-    if (scriptOptions.length === 0) {
-        log.warn('No scripts found in package.json — please ensure you have a start/dev script.');
-        cancel('No run script available.');
-        process.exit(1);
-    }
-    const runCommand = await select({
-        message: 'Which command starts your server?',
-        options: scriptOptions,
-    });
-    if (isCancel(runCommand)) {
-        cancel('Cancelled.');
-        process.exit(0);
-    }
     // ── Select backend ────────────────────────────────────────────────────────
     const backendChoice = await select({
         message: 'Send routes to',
@@ -122,13 +105,72 @@ async function main() {
     const isLocal = backendChoice === 'local';
     const backendUrl = isLocal ? BACKEND_LOCAL : BACKEND_PROD;
     const dashboardUrl = isLocal ? DASHBOARD_LOCAL : DASHBOARD_PROD;
+    // ── Detect architecture type ─────────────────────────────────────────────
+    const archResult = detectArchitectureType(process.cwd());
+    const archLabel = {
+        'monolithic': cyan('Monolithic'),
+        'modular-monolithic': cyan('Modular Monolithic'),
+        'microservices': cyan('Microservices'),
+    };
+    // ── Full multi-service mode when apiforge.config.json exists ─────────────
+    if (archResult.type === 'microservices') {
+        let microConfig = loadMicroConfig();
+        // Auto-create apiforge.config.json if not present
+        if (!microConfig) {
+            microConfig = await buildAndSaveConfig(projectName);
+        }
+        if (microConfig && microConfig.services.length > 0) {
+            log.info(dim('─────────────────────────────────────────────────'));
+            log.info(`${dim('Project:')}       ${bold(projectName)}`);
+            log.info(`${dim('Backend:')}       ${cyan(backendUrl)}`);
+            log.info(`${dim('Architecture:')}  ${archLabel['microservices']}`);
+            log.info(`${dim('Services:')}      ${bold(String(microConfig.services.length))} ${dim('(from apiforge.config.json)')}`);
+            log.info(dim('─────────────────────────────────────────────────'));
+            await microservicesFlow(microConfig, { projectName, apiKey, baseUrl, backendUrl, dashboardUrl });
+            return;
+        }
+    }
+    // ── Single-service: ask for run command ───────────────────────────────────
+    const scripts = detectScripts();
+    const scriptOptions = scripts.map(s => ({
+        value: s.command,
+        label: `${bold(s.name)}  ${dim('→')}  ${dim(s.command)}`,
+    }));
+    if (scriptOptions.length === 0) {
+        log.warn('No scripts found in package.json — please ensure you have a start/dev script.');
+        cancel('No run script available.');
+        process.exit(1);
+    }
+    const runCommand = await select({
+        message: 'Which command starts your server?',
+        options: scriptOptions,
+    });
+    if (isCancel(runCommand)) {
+        cancel('Cancelled.');
+        process.exit(0);
+    }
+    if (archResult.type === 'microservices') {
+        note([
+            `${yellow('Microservices architecture detected.')}`,
+            '',
+            `${dim('Add an')} ${bold('apiforge.config.json')} ${dim('to document all services automatically:')}`,
+            '',
+            `  ${cyan('{ "services": [{ "name": "auth", "dir": "./services/auth" }] }')}`,
+            '',
+            `${dim('For now, analyzing the single service started by the selected command.')}`,
+        ].join('\n'), 'Multi-service tip');
+    }
     log.info(dim('─────────────────────────────────────────────────'));
-    log.info(`${dim('Project:')}  ${bold(projectName)}`);
-    log.info(`${dim('Command:')}  ${bold(runCommand)}`);
-    log.info(`${dim('Backend:')}  ${cyan(backendUrl)}`);
+    log.info(`${dim('Project:')}       ${bold(projectName)}`);
+    log.info(`${dim('Command:')}       ${bold(runCommand)}`);
+    log.info(`${dim('Backend:')}       ${cyan(backendUrl)}`);
+    log.info(`${dim('Architecture:')}  ${archLabel[archResult.type]}`);
     log.info(dim('─────────────────────────────────────────────────'));
+    if (archResult.moduleNames.length > 0) {
+        log.info(`${dim('Modules found:')} ${archResult.moduleNames.map(m => bold(m)).join(', ')}`);
+    }
     // ── Detect & patch entry file ─────────────────────────────────────────────
-    const entryFile = detectEntryFile() ?? await askEntryFile();
+    const entryFile = detectEntryFile(archResult.type) ?? await askEntryFile(archResult.type);
     let injected = false;
     let linesAdded = 0;
     await tasks([
@@ -151,7 +193,7 @@ async function main() {
                 tryUnlink(join(process.cwd(), LOCK_FILE));
                 // Store API key in .env.local — never embed it in source code
                 persistApiKeyToEnv(apiKey);
-                const result = injectCode(entryFile, projectName, apiKey, baseUrl, backendUrl);
+                const result = injectCode(entryFile, projectName, apiKey, baseUrl, backendUrl, archResult.type);
                 injected = !result.alreadyInjected;
                 linesAdded = result.linesAdded ?? 0;
                 if (result.alreadyInjected) {
@@ -248,6 +290,288 @@ async function main() {
     }[approval.status];
     outro(outroMsg);
 }
+/**
+ * Scan the project for services and interactively write apiforge.config.json.
+ * Called when microservices arch is detected but no config file exists yet.
+ */
+async function buildAndSaveConfig(projectName) {
+    const cwd = process.cwd();
+    // Collect services from filesystem scan (same logic as findServiceEntries but raw)
+    const discovered = [];
+    for (const parentDir of ['services', 'apps', 'packages', 'microservices', 'src/services']) {
+        const parentPath = join(cwd, parentDir);
+        if (!existsSync(parentPath))
+            continue;
+        try {
+            const subdirs = readdirSync(parentPath, { withFileTypes: true }).filter(d => d.isDirectory());
+            for (const subdir of subdirs) {
+                const entry = findEntryInDir(join(parentPath, subdir.name));
+                if (entry) {
+                    discovered.push({ name: subdir.name, dir: `./${parentDir}/${subdir.name}` });
+                }
+            }
+        }
+        catch { }
+        if (discovered.length > 0)
+            break;
+    }
+    if (discovered.length === 0)
+        return null;
+    note([
+        bold(`Found ${discovered.length} service${discovered.length > 1 ? 's' : ''}:`),
+        '',
+        ...discovered.map(s => `  ${dim('·')} ${bold(s.name)}  ${dim('→')}  ${dim(s.dir)}`),
+        '',
+        `${dim('apiforge.config.json will be created so you never have to set this up again.')}`,
+    ].join('\n'), 'Auto-detected services');
+    const shouldCreate = await confirm({
+        message: `Create apiforge.config.json with these ${discovered.length} services?`,
+        initialValue: true,
+    });
+    if (isCancel(shouldCreate) || !shouldCreate)
+        return null;
+    const config = {
+        projectName,
+        architectureType: 'microservices',
+        services: discovered.map(s => ({ name: s.name, dir: s.dir })),
+    };
+    writeFileSync(join(cwd, 'apiforge.config.json'), JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    log.success(green(`✓ Created apiforge.config.json  (${discovered.length} services)`));
+    log.info(dim('  Commit this file so teammates can run apiforge without re-setup.'));
+    return { services: discovered };
+}
+function loadMicroConfig() {
+    for (const cfgName of ['apiforge.config.json', '.apiforge.json']) {
+        try {
+            const cfg = JSON.parse(readFileSync(join(process.cwd(), cfgName), 'utf-8'));
+            if (Array.isArray(cfg.services) && cfg.services.length > 0) {
+                return { projectName: cfg.projectName, services: cfg.services };
+            }
+        }
+        catch { }
+    }
+    return null;
+}
+function serviceNodeCommand(entryRelPath) {
+    if (entryRelPath.endsWith('.ts')) {
+        const hasTsx = existsSync(join(process.cwd(), 'node_modules/.bin/tsx'));
+        const hasTsNode = existsSync(join(process.cwd(), 'node_modules/.bin/ts-node'));
+        if (hasTsx)
+            return `node_modules/.bin/tsx ${entryRelPath}`;
+        if (hasTsNode)
+            return `node_modules/.bin/ts-node ${entryRelPath}`;
+        return `npx --yes tsx ${entryRelPath}`;
+    }
+    return `node ${entryRelPath}`;
+}
+function waitForServiceStatusFile(statusFile, timeoutMs) {
+    return new Promise(resolve => {
+        const fullPath = join(process.cwd(), statusFile);
+        const poller = setInterval(() => {
+            try {
+                if (!existsSync(fullPath))
+                    return;
+                const data = JSON.parse(readFileSync(fullPath, 'utf-8'));
+                if (data.status === 'collected' && Array.isArray(data.routes)) {
+                    clearInterval(poller);
+                    clearTimeout(timer);
+                    resolve(data.routes);
+                }
+            }
+            catch { }
+        }, 500);
+        const timer = setTimeout(() => {
+            clearInterval(poller);
+            resolve(null);
+        }, timeoutMs);
+    });
+}
+function hasDockerCompose(cwd) {
+    return ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml']
+        .some(f => existsSync(join(cwd, f)));
+}
+async function microservicesFlow(config, opts) {
+    const cwd = process.cwd();
+    const allRoutes = [];
+    const serviceMeta = [];
+    const injectedFiles = [];
+    // Clear any stale per-service status files
+    for (const svc of config.services) {
+        tryUnlink(join(cwd, `.apiforge-status-${svc.name}.json`));
+    }
+    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' : ''}…`),
+        '',
+        ...config.services.map(s => `  ${dim('·')} ${bold(s.name)}  ${dim('→')}  ${dim(s.dir)}`),
+        '',
+        dim('Each service is started individually and its routes are collected.'),
+    ].join('\n'), 'Multi-service analysis');
+    for (const svc of config.services) {
+        const svcSpin = spinner();
+        svcSpin.start(`${bold(svc.name)} — starting…`);
+        const svcDir = svc.dir.replace(/^\.\//, '');
+        // Resolve entry file
+        const relEntry = svc.entryFile ?? findEntryInDir(join(cwd, svcDir));
+        if (!relEntry) {
+            svcSpin.stop(yellow(`◌ ${svc.name} — no entry file found, skipping`));
+            continue;
+        }
+        const fullEntry = join(svcDir, relEntry);
+        const statusFile = `.apiforge-status-${svc.name}.json`;
+        // Inject collection snippet (upload: false, writes to per-service status file)
+        injectCode(fullEntry, opts.projectName, opts.apiKey, opts.baseUrl, opts.backendUrl, 'microservices', {
+            serviceName: svc.name,
+            statusFile,
+        });
+        injectedFiles.push(fullEntry);
+        // Start service with plain node (or tsx for .ts files)
+        const startCmd = svc.startCommand ?? serviceNodeCommand(fullEntry);
+        const child = spawn(startCmd, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: true,
+            env: { ...process.env },
+            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.
+        let output = '';
+        const MAX_OUTPUT = 4000;
+        const capture = (chunk) => {
+            output += chunk.toString();
+            if (output.length > MAX_OUTPUT)
+                output = output.slice(-MAX_OUTPUT);
+        };
+        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
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { }
+        tryUnlink(join(cwd, statusFile));
+        if (routes && routes.length > 0) {
+            const annotated = routes.map((r) => ({ ...r, service: svc.name }));
+            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(-20).map(l => `   ${l}`).join('\n')));
+            }
+        }
+        // Remove injected code
+        removeInjectedCode(fullEntry);
+        injectedFiles.splice(injectedFiles.indexOf(fullEntry), 1);
+    }
+    // Safety: clean up any remaining injections (e.g. if process was interrupted)
+    for (const f of injectedFiles)
+        removeInjectedCode(f);
+    if (allRoutes.length === 0) {
+        log.error(red('No routes were collected from any service.'));
+        outro(red('Analysis failed.'));
+        process.exit(1);
+    }
+    // Upload aggregated routes
+    const uploadSpin = spinner();
+    uploadSpin.start(`Uploading ${allRoutes.length} routes from ${serviceMeta.length} service${serviceMeta.length > 1 ? 's' : ''}…`);
+    const uploadResult = await uploadRoutes(allRoutes, {
+        projectName: opts.projectName,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl,
+        apiForgeUrl: opts.backendUrl,
+        architectureType: 'microservices',
+        services: serviceMeta,
+    });
+    if (!uploadResult) {
+        uploadSpin.stop(red('✗ Upload failed'));
+        outro(red('Analysis failed.'));
+        process.exit(1);
+    }
+    uploadSpin.stop(green(`✓ ${uploadResult.routeCount} routes submitted across ${serviceMeta.length} service${serviceMeta.length > 1 ? 's' : ''}`));
+    // ── Poll for dashboard approval ───────────────────────────────────────────
+    note([
+        bold('Open your dashboard to review:'),
+        '',
+        `  ${cyan(opts.dashboardUrl)}`,
+        '',
+        dim('In "Import JSON" → "Pending CLI Imports"'),
+        dim('Accept to start AI processing  ·  Deny to discard.'),
+    ].join('\n'), 'Action required');
+    const poll = spinner();
+    poll.start('Waiting for your decision in the dashboard…  (5 min timeout)');
+    const approval = await pollForApproval(uploadResult.pendingImportId, opts.apiKey, opts.backendUrl, 5 * 60000);
+    const statusMsg = {
+        approved: green('✓ Accepted — AI processing started!'),
+        denied: red('✗ Import denied by dashboard.'),
+        timeout: yellow('◌ Timed out — no decision made within 5 minutes.'),
+    }[approval.status];
+    poll.stop(statusMsg);
+    if (approval.status === 'approved') {
+        note([
+            bold('Your API is being documented.'),
+            '',
+            `  ${dim('Track progress:')}  ${cyan(opts.dashboardUrl)}`,
+            `  ${dim('Import ID:')}       ${dim(uploadResult.pendingImportId)}`,
+        ].join('\n'), 'Processing');
+    }
+    else if (approval.status === 'denied') {
+        note([
+            `  ${bold('You denied this import from the dashboard.')}`,
+            '',
+            `  ${dim('No documentation was generated.')}`,
+            `  ${dim('Run')} ${cyan('npx apiforge')} ${dim('again whenever you\'re ready.')}`,
+        ].join('\n'), 'Denied');
+    }
+    else {
+        note([
+            `  ${dim('Your import is still pending:')}`,
+            `  ${cyan(opts.dashboardUrl)}`,
+            '',
+            `  ${dim('Import ID:')}  ${cyan(uploadResult.pendingImportId)}`,
+            `  ${dim('You can still accept or deny it from the dashboard.')}`,
+        ].join('\n'), 'Pending');
+    }
+    tryUnlink(join(cwd, STATUS_FILE));
+    tryUnlink(join(cwd, LOCK_FILE));
+    const outroMsg = {
+        approved: `${green('✓')}  Done! View your AI docs at ${cyan(opts.dashboardUrl)}`,
+        denied: `${red('✗')}  Import denied. No changes were made.`,
+        timeout: `${yellow('◌')}  Timed out. Your import is still pending at ${cyan(opts.dashboardUrl)}`,
+    }[approval.status];
+    outro(outroMsg);
+}
 function startAndWaitForAnalysis(command, timeoutMs) {
     return new Promise(resolve => {
         const statusPath = join(process.cwd(), STATUS_FILE);
@@ -379,9 +703,124 @@ function removeInjectedCode(filePath) {
         return false;
     }
 }
-// ─── Entry file detection ─────────────────────────────────────────────────────
-function detectEntryFile() {
+/** Look for a server entry inside a single directory (checks src/ then root). */
+function findEntryInDir(absDir) {
+    const names = ['index', 'server', 'app', 'main'];
+    const exts = ['ts', 'js', 'mjs', 'cjs'];
+    for (const depth of ['src', '']) {
+        for (const name of names) {
+            for (const ext of exts) {
+                const rel = depth ? join(depth, `${name}.${ext}`) : `${name}.${ext}`;
+                if (existsSync(join(absDir, rel)))
+                    return rel;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Detect the project's root/main entry point — package.json main,
+ * common gateway directories, then flat root candidates.
+ * Returns a relative path or null.
+ */
+function detectMainEntry(cwd) {
+    // 1. package.json main / start / dev script
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
+        if (pkg.main && existsSync(join(cwd, pkg.main)))
+            return pkg.main;
+        for (const s of ['start', 'dev', 'serve']) {
+            const cmd = pkg.scripts?.[s] ?? '';
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+([^\s&|;]+\.(js|ts|mjs|cjs))/);
+            if (m && existsSync(join(cwd, m[1])))
+                return m[1];
+        }
+    }
+    catch { }
+    // 2. Common gateway/proxy directory (e.g. api-gateway/)
+    for (const gatewayDir of ['api-gateway', 'gateway', 'proxy', 'api-proxy']) {
+        const entry = findEntryInDir(join(cwd, gatewayDir));
+        if (entry)
+            return join(gatewayDir, entry);
+    }
+    // 3. Flat root candidates
+    for (const c of [
+        'index.ts', 'server.ts', 'app.ts', 'main.ts',
+        'index.js', 'server.js', 'app.js', 'main.js',
+        'src/index.ts', 'src/server.ts', 'src/app.ts', 'src/main.ts',
+        'src/index.js', 'src/server.js', 'src/app.js', 'src/main.js',
+    ]) {
+        if (existsSync(join(cwd, c)))
+            return c;
+    }
+    return null;
+}
+/**
+ * Scan the project for per-service entry files.
+ * Prepends the root main entry (if any) so it appears first in the select list.
+ * Reads apiforge.config.json first; falls back to common service parent dirs.
+ */
+function findServiceEntries() {
+    const cwd = process.cwd();
+    const results = [];
+    // 0. Root / main entry — shown first so the user always sees it
+    const mainEntry = detectMainEntry(cwd);
+    if (mainEntry) {
+        results.push({ label: `[ Main entry ]  →  ${mainEntry}`, path: mainEntry });
+    }
+    // 1. Authoritative list from apiforge.config.json / .apiforge.json
+    for (const cfgName of ['apiforge.config.json', '.apiforge.json']) {
+        try {
+            const cfg = JSON.parse(readFileSync(join(cwd, cfgName), 'utf-8'));
+            if (!Array.isArray(cfg.services) || cfg.services.length === 0)
+                continue;
+            for (const svc of cfg.services) {
+                const dir = svc.dir.replace(/^\.\//, '');
+                const entry = findEntryInDir(join(cwd, dir));
+                if (!entry)
+                    continue;
+                const relPath = join(dir, entry);
+                // Skip if same path as the main entry already added
+                if (relPath !== mainEntry) {
+                    results.push({ label: `${svc.name}  →  ${relPath}`, path: relPath });
+                }
+            }
+            if (results.length > 0)
+                return results;
+        }
+        catch { }
+    }
+    // 2. Filesystem scan of common service parent dirs
+    for (const parentDir of ['services', 'apps', 'packages', 'src/services', 'microservices']) {
+        const parentPath = join(cwd, parentDir);
+        if (!existsSync(parentPath))
+            continue;
+        try {
+            const subdirs = readdirSync(parentPath, { withFileTypes: true }).filter(d => d.isDirectory());
+            for (const subdir of subdirs) {
+                const entry = findEntryInDir(join(parentPath, subdir.name));
+                if (!entry)
+                    continue;
+                const relPath = join(parentDir, subdir.name, entry);
+                if (relPath !== mainEntry) {
+                    results.push({ label: `${subdir.name}  →  ${relPath}`, path: relPath });
+                }
+            }
+        }
+        catch { }
+        if (results.length > 1)
+            return results; // >1 because main entry is already at index 0
+    }
+    return results;
+}
+function detectEntryFile(archType) {
     const cwd = process.cwd();
+    // For microservices: auto-pick only when exactly one service entry is found
+    if (archType === 'microservices') {
+        const entries = findServiceEntries();
+        return entries.length === 1 ? entries[0].path : null;
+    }
+    // Package.json hints
     try {
         const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && existsSync(join(cwd, pkg.main)))
@@ -394,16 +833,47 @@ function detectEntryFile() {
         }
     }
     catch { }
+    // Flat file candidates — root → src/ → compiled output → misc
     const candidates = [
-        'index.ts', 'server.ts', 'app.ts',
-        'index.js', 'server.js', 'app.js',
-        'src/index.ts', 'src/server.ts', 'src/app.ts',
-        'src/index.js', 'src/server.js', 'src/app.js',
+        'index.ts', 'server.ts', 'app.ts', 'main.ts',
+        'index.js', 'server.js', 'app.js', 'main.js',
+        'src/index.ts', 'src/server.ts', 'src/app.ts', 'src/main.ts',
+        'src/index.js', 'src/server.js', 'src/app.js', 'src/main.js',
+        'dist/index.js', 'dist/server.js', 'dist/main.js',
+        'build/index.js', 'build/server.js', 'build/main.js',
+        'lib/index.js', 'lib/server.js',
+        'server/index.ts', 'server/index.js',
+        'api/index.ts', 'api/index.js',
+        'src/server/index.ts', 'src/server/index.js',
+        'lambda.ts', 'lambda.js', 'handler.ts', 'handler.js',
     ];
     return candidates.find(c => existsSync(join(cwd, c))) ?? null;
 }
-async function askEntryFile() {
-    log.warn('Could not auto-detect your server entry file.');
+async function askEntryFile(archType) {
+    if (archType === 'microservices') {
+        const entries = findServiceEntries();
+        if (entries.length > 0) {
+            const choice = await select({
+                message: 'Which service entry file do you want to analyze?',
+                options: [
+                    ...entries.map(e => ({ value: e.path, label: e.label })),
+                    { value: '__manual', label: 'Enter path manually…' },
+                ],
+            });
+            if (isCancel(choice)) {
+                cancel('Cancelled.');
+                process.exit(0);
+            }
+            if (choice !== '__manual')
+                return choice;
+        }
+        else {
+            log.warn('Could not find service entry files in services/, apps/, or packages/.');
+        }
+    }
+    else {
+        log.warn('Could not auto-detect your server entry file.');
+    }
     const custom = await text({
         message: 'Path to your server entry file',
         placeholder: 'src/index.ts',
@@ -431,7 +901,7 @@ function detectScripts() {
             if (scripts[name])
                 result.push({ name, command: `npm run ${name}` });
         }
-        // Then any remaining scripts that look like server starters
+        // Scripts that directly invoke a node runtime
         for (const [name, cmd] of Object.entries(scripts)) {
             if (preferred.includes(name))
                 continue;
@@ -439,13 +909,22 @@ function detectScripts() {
                 result.push({ name, command: `npm run ${name}` });
             }
         }
+        // Workspace per-service scripts: start:*, dev:*, serve:* patterns
+        // (e.g. "dev:auth", "start:wallet" common in npm/pnpm monorepos)
+        for (const [name] of Object.entries(scripts)) {
+            if (preferred.includes(name))
+                continue;
+            if (/^(?:start|dev|serve|run):[a-z0-9_-]+$/i.test(name) && !result.some(r => r.name === name)) {
+                result.push({ name, command: `npm run ${name}` });
+            }
+        }
         return result;
     }
     catch {
         return [];
     }
 }
-function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl) {
+function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl, architectureType, collectionOpts) {
     const fullPath = join(process.cwd(), filePath);
     const content = readFileSync(fullPath, 'utf-8');
     if (content.includes('apiforge-analyzer')) {
@@ -453,9 +932,16 @@ function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl) {
     }
     const isESM = detectESM(filePath, content);
     const appVar = detectAppVariable(content) ?? 'app';
-    const snippet = buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM);
+    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) {
@@ -504,19 +990,34 @@ function addToGitignore(pattern) {
     }
     catch { }
 }
-function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM) {
+function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, architectureType, collectionOpts) {
     // The API key is embedded directly — this snippet is TEMPORARY (auto-removed after analysis).
     // Hardcoding guarantees the same key is used for both submit and CLI status polling,
     // eliminating the mismatch that causes 401s when .env.local already has a different key.
     const isProd = backendUrl === BACKEND_PROD;
-    const opts = [
-        `    apiKey: '${apiKey}',`,
-        `    projectName: '${projectName}',`,
-        `    baseUrl: '${baseUrl}',`,
-        ...(isProd ? [] : [`    apiForgeUrl: '${backendUrl}',`]),
-        `    upload: true,`,
-        `    runOnce: true,`,
-    ].join('\n');
+    // Collection mode (multi-service): upload: false, write to per-service status file
+    const opts = collectionOpts
+        ? [
+            `    apiKey: '${apiKey}',`,
+            `    projectName: '${projectName}',`,
+            `    baseUrl: '${baseUrl}',`,
+            `    service: '${collectionOpts.serviceName}',`,
+            `    statusFile: '${collectionOpts.statusFile}',`,
+            `    architectureType: 'microservices',`,
+            `    upload: false,`,
+            `    runOnce: true,`,
+        ].join('\n')
+        : [
+            `    apiKey: '${apiKey}',`,
+            `    projectName: '${projectName}',`,
+            `    baseUrl: '${baseUrl}',`,
+            ...(isProd ? [] : [`    apiForgeUrl: '${backendUrl}',`]),
+            ...(architectureType && architectureType !== 'monolithic'
+                ? [`    architectureType: '${architectureType}',`]
+                : []),
+            `    upload: true,`,
+            `    runOnce: true,`,
+        ].join('\n');
     if (isESM) {
         return [
             `// APIForge — https://apiforge.brainfogagency.com`,