apiforge-analyzer 1.3.3 → 1.3.6

package/dist/cjs/cli.js

@@ -205,7 +205,9 @@ async function main() {
                     return `${yellow('◌')} Already configured — no changes made`;
                 }
                 return [
-                    `${green('✓')} Patched ${bold(entryFile)}  ${dim(`+${linesAdded} lines`)}`,
+                    result.updated
+                        ? `${green('✓')} Updated ${bold(entryFile)}  ${dim('(project name/API key changed since last run)')}`
+                        : `${green('✓')} Patched ${bold(entryFile)}  ${dim(`+${linesAdded} lines`)}`,
                     `   ${green('✓')} API key saved to ${bold('.env.local')}  ${dim('(gitignored)')}`,
                 ].join('\n');
             },
@@ -220,7 +222,19 @@ async function main() {
     ].join('\n'), 'Running');
     const s = (0, prompts_1.spinner)();
     s.start('Starting server and analyzing routes…');
-    const serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    // If the dev command runs under nodemon, our own STATUS_FILE/LOCK_FILE
+    // writes (both plain .json files inside the project root) are themselves
+    // inside nodemon's default watch glob — writing them mid-analysis makes
+    // nodemon restart the very server we're trying to analyze, racing the old
+    // and new process for the port (EADDRINUSE) and hanging the whole run.
+    const restoreNodemonIgnore = suppressNodemonSelfRestart(process.cwd());
+    let serverResult;
+    try {
+        serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    }
+    finally {
+        restoreNodemonIgnore();
+    }
     if (serverResult.status === 'error') {
         s.stop(red(`✗ ${serverResult.message}`));
         // Give a targeted hint for common failure modes
@@ -653,11 +667,10 @@ async function microservicesFlow(config, opts) {
         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 { }
+        // Kill service process (and its full descendant tree — see killProcessTree)
+        if (child.pid)
+            killProcessTree(child.pid);
+        await killOrphanFromEaddrinuse(output);
         tryUnlink((0, path_1.join)(cwd, statusFile));
         if (routes && routes.length > 0) {
             const prefix = gatewayPrefixes[svc.name];
@@ -759,6 +772,124 @@ async function microservicesFlow(config, opts) {
     }[approval.status];
     (0, prompts_1.outro)(outroMsg);
 }
+// ─── Server subprocess ────────────────────────────────────────────────────────
+/**
+ * Kill the whole process tree rooted at `pid`, not just that one process.
+ *
+ * The dev server is started via `spawn(command, { shell: true })`, so `pid`
+ * is the shell (cmd.exe /c "npm run dev") — `child.kill()` only signals that
+ * shell. On Windows, that leaves the real descendants (npm → nodemon → node)
+ * running and still holding the port, so the very next run immediately hits
+ * EADDRINUSE. `taskkill /T` kills the shell's entire descendant tree instead.
+ * On POSIX this isn't needed the same way (SIGTERM propagates to the shell's
+ * job, and the analyzer process itself exits cleanly), so a plain kill there
+ * is enough.
+ */
+function killProcessTree(pid) {
+    if (process.platform === 'win32') {
+        try {
+            (0, child_process_1.spawn)('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        catch { }
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { }
+    }
+}
+/**
+ * nodemon manages its own child process in a way that doesn't always show
+ * up as a descendant of the shell pid `killProcessTree` targets —
+ * `taskkill /T` walks the OS-reported parent/child tree, but nodemon's
+ * actual worker sometimes isn't linked into that tree on Windows, so it
+ * survives our kill and keeps holding its port. That port then collides
+ * with the very next run (EADDRINUSE), which gets killed the same
+ * incomplete way, and orphans keep piling up across retries.
+ *
+ * Rather than guess at process relationships, read the actual port back
+ * out of "EADDRINUSE...:<port>" in the crashed server's own output (Node
+ * always includes it) and kill whatever OS-level listener currently holds
+ * that port — this is exact, not a heuristic, and clears the pileup so the
+ * next run isn't born already colliding with the previous one.
+ */
+function killOrphanFromEaddrinuse(serverOutput) {
+    return new Promise(resolve => {
+        if (process.platform !== 'win32')
+            return resolve();
+        const match = serverOutput.match(/EADDRINUSE.*?:(\d+)\b/);
+        if (!match)
+            return resolve();
+        const port = match[1];
+        const script = `Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }`;
+        try {
+            // Must be awaited (not fire-and-forget) — the CLI process exits right
+            // after calling this, and an un-awaited spawn() can get cut off
+            // before PowerShell finishes actually killing anything, silently
+            // undoing the whole point of this cleanup.
+            const ps = (0, child_process_1.spawn)('powershell', ['-NoProfile', '-Command', script], { stdio: 'ignore' });
+            ps.on('exit', () => resolve());
+            ps.on('error', () => resolve());
+            // Don't let a hung PowerShell block the CLI from ever exiting.
+            setTimeout(resolve, 5000);
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+const NODEMON_IGNORE_PATTERNS = ['.apiforge-status.json', '.apiforge-last-run.json', '.env.local'];
+/**
+ * If the project depends on nodemon, make sure it won't watch our own
+ * .apiforge-status.json / .apiforge-last-run.json / .env.local writes —
+ * nodemon's default watch glob includes *.json, so without this it restarts
+ * the app mid-analysis (racing the old and new process for the port) every
+ * time analyze() writes its completion signal.
+ *
+ * Uses nodemon's own `.nodemonignore` file (read automatically if present,
+ * no config changes needed). Creates it if absent, or appends any missing
+ * patterns if it already exists — then returns a function that restores
+ * whatever was there before (or removes the file if we created it).
+ */
+function suppressNodemonSelfRestart(cwd) {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(cwd, 'package.json'), 'utf-8'));
+        const usesNodemon = !!(pkg.dependencies?.nodemon || pkg.devDependencies?.nodemon);
+        if (!usesNodemon)
+            return () => { };
+    }
+    catch {
+        return () => { };
+    }
+    const ignorePath = (0, path_1.join)(cwd, '.nodemonignore');
+    const existed = (0, fs_1.existsSync)(ignorePath);
+    const original = existed ? (0, fs_1.readFileSync)(ignorePath, 'utf-8') : '';
+    const existingLines = new Set(original.split('\n').map(l => l.trim()).filter(Boolean));
+    const missing = NODEMON_IGNORE_PATTERNS.filter(p => !existingLines.has(p));
+    if (missing.length === 0)
+        return () => { };
+    try {
+        const next = existed
+            ? original.trimEnd() + '\n' + missing.join('\n') + '\n'
+            : missing.join('\n') + '\n';
+        (0, fs_1.writeFileSync)(ignorePath, next, 'utf-8');
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        try {
+            if (existed) {
+                (0, fs_1.writeFileSync)(ignorePath, original, 'utf-8');
+            }
+            else {
+                (0, fs_1.unlinkSync)(ignorePath);
+            }
+        }
+        catch { }
+    };
+}
 function startAndWaitForAnalysis(command, timeoutMs) {
     return new Promise(resolve => {
         const statusPath = (0, path_1.join)(process.cwd(), STATUS_FILE);
@@ -785,11 +916,11 @@ function startAndWaitForAnalysis(command, timeoutMs) {
             resolved = true;
             clearInterval(poller);
             clearTimeout(timeout);
-            try {
-                child.kill('SIGTERM');
-            }
-            catch { }
-            resolve({ ...result, serverOutput: serverOutput.trim() });
+            if (child.pid)
+                killProcessTree(child.pid);
+            killOrphanFromEaddrinuse(serverOutput).then(() => {
+                resolve({ ...result, serverOutput: serverOutput.trim() });
+            });
         }
         // Poll for the status file every 500 ms
         const poller = setInterval(() => {
@@ -899,6 +1030,28 @@ function removeInjectedCode(filePath) {
         return false;
     }
 }
+// ─── Entry file detection ─────────────────────────────────────────────────────
+/**
+ * If `candidate` looks like compiled build output (dist/build/out/lib) and a
+ * TypeScript source with the same base name exists under src/, prefer that
+ * instead of the build artifact.
+ *
+ * Injecting into dist/index.js is worse than pointless when the project has
+ * a watch compiler (tsc --watch, common in a "dev" script alongside
+ * nodemon watching that same dist folder): the compiler immediately
+ * overwrites the file with a fresh, uninjected build, and that overwrite
+ * itself looks like a file change to nodemon, which restarts the server —
+ * colliding with the still-running instance that had the injected snippet
+ * and racing it for the port (EADDRINUSE). The injected code also can't be
+ * cleaned up afterward because tsc already erased it before cleanup ran.
+ */
+function preferSourceOverBuildOutput(cwd, candidate) {
+    const match = candidate.match(/^(?:dist|build|out|lib)[\\/](.+)\.(?:js|mjs|cjs)$/);
+    if (!match)
+        return candidate;
+    const srcCandidate = (0, path_1.join)('src', `${match[1]}.ts`);
+    return (0, fs_1.existsSync)((0, path_1.join)(cwd, srcCandidate)) ? srcCandidate : candidate;
+}
 /** Look for a server entry inside a single directory (checks src/ then root). */
 function findEntryInDir(absDir) {
     const names = ['index', 'server', 'app', 'main'];
@@ -924,12 +1077,12 @@ function detectMainEntry(cwd) {
     try {
         const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && (0, fs_1.existsSync)((0, path_1.join)(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, 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))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && (0, fs_1.existsSync)((0, path_1.join)(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1020,12 +1173,12 @@ function detectEntryFile(archType) {
     try {
         const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && (0, fs_1.existsSync)((0, path_1.join)(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, 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))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && (0, fs_1.existsSync)((0, path_1.join)(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1120,11 +1273,37 @@ function detectScripts() {
         return [];
     }
 }
+/** Reads `field: 'value'` out of an already-injected APIForge block. */
+function extractInjectedField(block, field) {
+    const m = new RegExp(`${field}:\\s*'([^']*)'`).exec(block);
+    return m?.[1];
+}
 function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl, architectureType, collectionOpts) {
     const fullPath = (0, path_1.join)(process.cwd(), filePath);
-    const content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
-    if (content.includes('apiforge-analyzer')) {
-        return { alreadyInjected: true };
+    let content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
+    const startIdx = content.indexOf('// APIForge');
+    let wasStale = false;
+    if (startIdx !== -1) {
+        const afterStart = content.slice(startIdx);
+        const endMatch = /\.catch\s*\(\s*\(\s*\)\s*=>\s*\{?\s*\}?\s*\)\s*\n?/.exec(afterStart);
+        const block = endMatch ? afterStart.slice(0, endMatch.index + endMatch[0].length) : afterStart;
+        const existingKey = extractInjectedField(block, 'apiKey');
+        const existingName = extractInjectedField(block, 'projectName');
+        // Same project name and API key as last time — nothing to do.
+        if (existingKey === apiKey && existingName === projectName) {
+            return { alreadyInjected: true };
+        }
+        // Prompt answers changed since this file was last configured. Silently
+        // keeping the old block meant a stale (sometimes since-deleted) API key
+        // stayed hardcoded forever — every later run kept uploading with it no
+        // matter what was typed at the prompt. Re-inject fresh instead.
+        if (endMatch) {
+            const endIdx = startIdx + endMatch.index + endMatch[0].length;
+            content = (content.slice(0, startIdx) + content.slice(endIdx))
+                .replace(/\n{3,}/g, '\n\n')
+                .trimEnd() + '\n';
+            wasStale = true;
+        }
     }
     const isESM = detectESM(filePath, content);
     const appVar = detectAppVariable(content) ?? 'app';
@@ -1150,7 +1329,7 @@ function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl, architec
         injectionPoint = 'end of file';
     }
     (0, fs_1.writeFileSync)(fullPath, newContent, 'utf-8');
-    return { alreadyInjected: false, injectionPoint, linesAdded: snippet.split('\n').length };
+    return { alreadyInjected: false, injectionPoint, linesAdded: snippet.split('\n').length, updated: wasStale };
 }
 /**
  * Write (or overwrite) the API key in .env.local.
@@ -1216,24 +1395,37 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
         ].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.
+    //
+    // Express exposes no "I'm done registering routes" signal, so for
+    // Express-shaped apps we poll app._router.stack briefly before giving up
+    // and collecting whatever is there — bounded well under the CLI's 30s
+    // per-service timeout so a hung connect still surfaces.
+    //
+    // Fastify DOES expose a real completion signal (`app.ready()`, resolved
+    // once every plugin/route has finished registering), so Fastify apps use
+    // that instead of the Express-shaped poll — polling `._router.stack` on a
+    // Fastify instance always looks "empty" (Fastify doesn't have that
+    // property), which used to make hasRoutes evaluate true immediately and
+    // fire analyze() before async-registered routes existed yet.
     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)`,
+            `  if (${appVar} && typeof ${appVar}.ready === 'function') {`,
+            `    ${appVar}.ready().then(() => { ${runAnalyze} }).catch(() => { ${runAnalyze} })`,
+            `  } else {`,
+            `    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()`,
             `  }`,
-            `  __apiforgeTryCollect()`,
         ].join('\n')
         : `  ${runAnalyze}`;
     if (isESM) {
@@ -1268,17 +1460,23 @@ function detectESM(filePath, content) {
     return /^(?:import|export)\s+/m.test(content);
 }
 function detectAppVariable(content) {
+    // Optional TS type annotation between the variable name and `=`, e.g.
+    // `const app: FastifyInstance = fastify()` — common in Fastify+TS
+    // projects (Fastify has first-class TS typings, unlike bare Express).
+    // Without this, none of the patterns below matched a type-annotated
+    // Fastify app at all.
+    const typeAnn = `(?:\\s*:\\s*[\\w.$]+(?:<[^>]*>)?)?`;
     const patterns = [
-        /(?:const|let|var)\s+(\w+)\s*=\s*express\s*(?:\.default)?\s*\(/,
-        /(?: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*\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*express\\s*(?:\\.default)?\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*(?:fastify|Fastify)\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*new\\s+Koa\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\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*)?\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*require\\s*\\(\\s*['"](?:fastify|express)['"]\\s*\\)\\s*(?:\\.default\\s*)?\\(`),
     ];
     for (const re of patterns) {
         const m = content.match(re);

package/dist/esm/cli.js

@@ -200,7 +200,9 @@ async function main() {
                     return `${yellow('◌')} Already configured — no changes made`;
                 }
                 return [
-                    `${green('✓')} Patched ${bold(entryFile)}  ${dim(`+${linesAdded} lines`)}`,
+                    result.updated
+                        ? `${green('✓')} Updated ${bold(entryFile)}  ${dim('(project name/API key changed since last run)')}`
+                        : `${green('✓')} Patched ${bold(entryFile)}  ${dim(`+${linesAdded} lines`)}`,
                     `   ${green('✓')} API key saved to ${bold('.env.local')}  ${dim('(gitignored)')}`,
                 ].join('\n');
             },
@@ -215,7 +217,19 @@ async function main() {
     ].join('\n'), 'Running');
     const s = spinner();
     s.start('Starting server and analyzing routes…');
-    const serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    // If the dev command runs under nodemon, our own STATUS_FILE/LOCK_FILE
+    // writes (both plain .json files inside the project root) are themselves
+    // inside nodemon's default watch glob — writing them mid-analysis makes
+    // nodemon restart the very server we're trying to analyze, racing the old
+    // and new process for the port (EADDRINUSE) and hanging the whole run.
+    const restoreNodemonIgnore = suppressNodemonSelfRestart(process.cwd());
+    let serverResult;
+    try {
+        serverResult = await startAndWaitForAnalysis(runCommand, 90000);
+    }
+    finally {
+        restoreNodemonIgnore();
+    }
     if (serverResult.status === 'error') {
         s.stop(red(`✗ ${serverResult.message}`));
         // Give a targeted hint for common failure modes
@@ -648,11 +662,10 @@ async function microservicesFlow(config, opts) {
         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 { }
+        // Kill service process (and its full descendant tree — see killProcessTree)
+        if (child.pid)
+            killProcessTree(child.pid);
+        await killOrphanFromEaddrinuse(output);
         tryUnlink(join(cwd, statusFile));
         if (routes && routes.length > 0) {
             const prefix = gatewayPrefixes[svc.name];
@@ -754,6 +767,124 @@ async function microservicesFlow(config, opts) {
     }[approval.status];
     outro(outroMsg);
 }
+// ─── Server subprocess ────────────────────────────────────────────────────────
+/**
+ * Kill the whole process tree rooted at `pid`, not just that one process.
+ *
+ * The dev server is started via `spawn(command, { shell: true })`, so `pid`
+ * is the shell (cmd.exe /c "npm run dev") — `child.kill()` only signals that
+ * shell. On Windows, that leaves the real descendants (npm → nodemon → node)
+ * running and still holding the port, so the very next run immediately hits
+ * EADDRINUSE. `taskkill /T` kills the shell's entire descendant tree instead.
+ * On POSIX this isn't needed the same way (SIGTERM propagates to the shell's
+ * job, and the analyzer process itself exits cleanly), so a plain kill there
+ * is enough.
+ */
+function killProcessTree(pid) {
+    if (process.platform === 'win32') {
+        try {
+            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        catch { }
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { }
+    }
+}
+/**
+ * nodemon manages its own child process in a way that doesn't always show
+ * up as a descendant of the shell pid `killProcessTree` targets —
+ * `taskkill /T` walks the OS-reported parent/child tree, but nodemon's
+ * actual worker sometimes isn't linked into that tree on Windows, so it
+ * survives our kill and keeps holding its port. That port then collides
+ * with the very next run (EADDRINUSE), which gets killed the same
+ * incomplete way, and orphans keep piling up across retries.
+ *
+ * Rather than guess at process relationships, read the actual port back
+ * out of "EADDRINUSE...:<port>" in the crashed server's own output (Node
+ * always includes it) and kill whatever OS-level listener currently holds
+ * that port — this is exact, not a heuristic, and clears the pileup so the
+ * next run isn't born already colliding with the previous one.
+ */
+function killOrphanFromEaddrinuse(serverOutput) {
+    return new Promise(resolve => {
+        if (process.platform !== 'win32')
+            return resolve();
+        const match = serverOutput.match(/EADDRINUSE.*?:(\d+)\b/);
+        if (!match)
+            return resolve();
+        const port = match[1];
+        const script = `Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }`;
+        try {
+            // Must be awaited (not fire-and-forget) — the CLI process exits right
+            // after calling this, and an un-awaited spawn() can get cut off
+            // before PowerShell finishes actually killing anything, silently
+            // undoing the whole point of this cleanup.
+            const ps = spawn('powershell', ['-NoProfile', '-Command', script], { stdio: 'ignore' });
+            ps.on('exit', () => resolve());
+            ps.on('error', () => resolve());
+            // Don't let a hung PowerShell block the CLI from ever exiting.
+            setTimeout(resolve, 5000);
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+const NODEMON_IGNORE_PATTERNS = ['.apiforge-status.json', '.apiforge-last-run.json', '.env.local'];
+/**
+ * If the project depends on nodemon, make sure it won't watch our own
+ * .apiforge-status.json / .apiforge-last-run.json / .env.local writes —
+ * nodemon's default watch glob includes *.json, so without this it restarts
+ * the app mid-analysis (racing the old and new process for the port) every
+ * time analyze() writes its completion signal.
+ *
+ * Uses nodemon's own `.nodemonignore` file (read automatically if present,
+ * no config changes needed). Creates it if absent, or appends any missing
+ * patterns if it already exists — then returns a function that restores
+ * whatever was there before (or removes the file if we created it).
+ */
+function suppressNodemonSelfRestart(cwd) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
+        const usesNodemon = !!(pkg.dependencies?.nodemon || pkg.devDependencies?.nodemon);
+        if (!usesNodemon)
+            return () => { };
+    }
+    catch {
+        return () => { };
+    }
+    const ignorePath = join(cwd, '.nodemonignore');
+    const existed = existsSync(ignorePath);
+    const original = existed ? readFileSync(ignorePath, 'utf-8') : '';
+    const existingLines = new Set(original.split('\n').map(l => l.trim()).filter(Boolean));
+    const missing = NODEMON_IGNORE_PATTERNS.filter(p => !existingLines.has(p));
+    if (missing.length === 0)
+        return () => { };
+    try {
+        const next = existed
+            ? original.trimEnd() + '\n' + missing.join('\n') + '\n'
+            : missing.join('\n') + '\n';
+        writeFileSync(ignorePath, next, 'utf-8');
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        try {
+            if (existed) {
+                writeFileSync(ignorePath, original, 'utf-8');
+            }
+            else {
+                unlinkSync(ignorePath);
+            }
+        }
+        catch { }
+    };
+}
 function startAndWaitForAnalysis(command, timeoutMs) {
     return new Promise(resolve => {
         const statusPath = join(process.cwd(), STATUS_FILE);
@@ -780,11 +911,11 @@ function startAndWaitForAnalysis(command, timeoutMs) {
             resolved = true;
             clearInterval(poller);
             clearTimeout(timeout);
-            try {
-                child.kill('SIGTERM');
-            }
-            catch { }
-            resolve({ ...result, serverOutput: serverOutput.trim() });
+            if (child.pid)
+                killProcessTree(child.pid);
+            killOrphanFromEaddrinuse(serverOutput).then(() => {
+                resolve({ ...result, serverOutput: serverOutput.trim() });
+            });
         }
         // Poll for the status file every 500 ms
         const poller = setInterval(() => {
@@ -894,6 +1025,28 @@ function removeInjectedCode(filePath) {
         return false;
     }
 }
+// ─── Entry file detection ─────────────────────────────────────────────────────
+/**
+ * If `candidate` looks like compiled build output (dist/build/out/lib) and a
+ * TypeScript source with the same base name exists under src/, prefer that
+ * instead of the build artifact.
+ *
+ * Injecting into dist/index.js is worse than pointless when the project has
+ * a watch compiler (tsc --watch, common in a "dev" script alongside
+ * nodemon watching that same dist folder): the compiler immediately
+ * overwrites the file with a fresh, uninjected build, and that overwrite
+ * itself looks like a file change to nodemon, which restarts the server —
+ * colliding with the still-running instance that had the injected snippet
+ * and racing it for the port (EADDRINUSE). The injected code also can't be
+ * cleaned up afterward because tsc already erased it before cleanup ran.
+ */
+function preferSourceOverBuildOutput(cwd, candidate) {
+    const match = candidate.match(/^(?:dist|build|out|lib)[\\/](.+)\.(?:js|mjs|cjs)$/);
+    if (!match)
+        return candidate;
+    const srcCandidate = join('src', `${match[1]}.ts`);
+    return existsSync(join(cwd, srcCandidate)) ? srcCandidate : candidate;
+}
 /** Look for a server entry inside a single directory (checks src/ then root). */
 function findEntryInDir(absDir) {
     const names = ['index', 'server', 'app', 'main'];
@@ -919,12 +1072,12 @@ function detectMainEntry(cwd) {
     try {
         const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && existsSync(join(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, 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))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && existsSync(join(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1015,12 +1168,12 @@ function detectEntryFile(archType) {
     try {
         const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8'));
         if (pkg.main && existsSync(join(cwd, pkg.main)))
-            return pkg.main;
+            return preferSourceOverBuildOutput(cwd, 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))/);
+            const m = cmd.match(/(?:node|tsx|ts-node|nodemon)\s+(?:-\S+\s+)*([^\s&|;]+\.(js|ts|mjs|cjs))/);
             if (m && existsSync(join(cwd, m[1])))
-                return m[1];
+                return preferSourceOverBuildOutput(cwd, m[1]);
         }
     }
     catch { }
@@ -1115,11 +1268,37 @@ function detectScripts() {
         return [];
     }
 }
+/** Reads `field: 'value'` out of an already-injected APIForge block. */
+function extractInjectedField(block, field) {
+    const m = new RegExp(`${field}:\\s*'([^']*)'`).exec(block);
+    return m?.[1];
+}
 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')) {
-        return { alreadyInjected: true };
+    let content = readFileSync(fullPath, 'utf-8');
+    const startIdx = content.indexOf('// APIForge');
+    let wasStale = false;
+    if (startIdx !== -1) {
+        const afterStart = content.slice(startIdx);
+        const endMatch = /\.catch\s*\(\s*\(\s*\)\s*=>\s*\{?\s*\}?\s*\)\s*\n?/.exec(afterStart);
+        const block = endMatch ? afterStart.slice(0, endMatch.index + endMatch[0].length) : afterStart;
+        const existingKey = extractInjectedField(block, 'apiKey');
+        const existingName = extractInjectedField(block, 'projectName');
+        // Same project name and API key as last time — nothing to do.
+        if (existingKey === apiKey && existingName === projectName) {
+            return { alreadyInjected: true };
+        }
+        // Prompt answers changed since this file was last configured. Silently
+        // keeping the old block meant a stale (sometimes since-deleted) API key
+        // stayed hardcoded forever — every later run kept uploading with it no
+        // matter what was typed at the prompt. Re-inject fresh instead.
+        if (endMatch) {
+            const endIdx = startIdx + endMatch.index + endMatch[0].length;
+            content = (content.slice(0, startIdx) + content.slice(endIdx))
+                .replace(/\n{3,}/g, '\n\n')
+                .trimEnd() + '\n';
+            wasStale = true;
+        }
     }
     const isESM = detectESM(filePath, content);
     const appVar = detectAppVariable(content) ?? 'app';
@@ -1145,7 +1324,7 @@ function injectCode(filePath, projectName, apiKey, baseUrl, backendUrl, architec
         injectionPoint = 'end of file';
     }
     writeFileSync(fullPath, newContent, 'utf-8');
-    return { alreadyInjected: false, injectionPoint, linesAdded: snippet.split('\n').length };
+    return { alreadyInjected: false, injectionPoint, linesAdded: snippet.split('\n').length, updated: wasStale };
 }
 /**
  * Write (or overwrite) the API key in .env.local.
@@ -1211,24 +1390,37 @@ function buildSnippet(projectName, apiKey, baseUrl, backendUrl, appVar, isESM, a
         ].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.
+    //
+    // Express exposes no "I'm done registering routes" signal, so for
+    // Express-shaped apps we poll app._router.stack briefly before giving up
+    // and collecting whatever is there — bounded well under the CLI's 30s
+    // per-service timeout so a hung connect still surfaces.
+    //
+    // Fastify DOES expose a real completion signal (`app.ready()`, resolved
+    // once every plugin/route has finished registering), so Fastify apps use
+    // that instead of the Express-shaped poll — polling `._router.stack` on a
+    // Fastify instance always looks "empty" (Fastify doesn't have that
+    // property), which used to make hasRoutes evaluate true immediately and
+    // fire analyze() before async-registered routes existed yet.
     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)`,
+            `  if (${appVar} && typeof ${appVar}.ready === 'function') {`,
+            `    ${appVar}.ready().then(() => { ${runAnalyze} }).catch(() => { ${runAnalyze} })`,
+            `  } else {`,
+            `    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()`,
             `  }`,
-            `  __apiforgeTryCollect()`,
         ].join('\n')
         : `  ${runAnalyze}`;
     if (isESM) {
@@ -1263,17 +1455,23 @@ function detectESM(filePath, content) {
     return /^(?:import|export)\s+/m.test(content);
 }
 function detectAppVariable(content) {
+    // Optional TS type annotation between the variable name and `=`, e.g.
+    // `const app: FastifyInstance = fastify()` — common in Fastify+TS
+    // projects (Fastify has first-class TS typings, unlike bare Express).
+    // Without this, none of the patterns below matched a type-annotated
+    // Fastify app at all.
+    const typeAnn = `(?:\\s*:\\s*[\\w.$]+(?:<[^>]*>)?)?`;
     const patterns = [
-        /(?:const|let|var)\s+(\w+)\s*=\s*express\s*(?:\.default)?\s*\(/,
-        /(?: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*\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*express\\s*(?:\\.default)?\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*(?:fastify|Fastify)\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*new\\s+Koa\\s*\\(`),
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\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*)?\(/,
+        new RegExp(`(?:const|let|var)\\s+(\\w+)${typeAnn}\\s*=\\s*require\\s*\\(\\s*['"](?:fastify|express)['"]\\s*\\)\\s*(?:\\.default\\s*)?\\(`),
     ];
     for (const re of patterns) {
         const m = content.match(re);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apiforge-analyzer",
-  "version": "1.3.3",
-  "description": "Universal API documentation generator for Express, Fastify, Next.js, Vite, React Router, and Node.js",
+  "version": "1.3.6",
+  "description": "Universal API documentation generator for Express, Next.js, Vite, React Router, and Node.js",
   "type": "module",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -54,14 +54,14 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
-    "axios": "^1.6.0"
+    "axios": "^1.6.0",
+    "ts-morph": "^28.0.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^20.0.0",
     "fastify": "^5.12.1",
-    "ts-morph": "^28.0.0",
     "typescript": "^5.3.0",
     "zod": "^4.5.4"
   }
-}
+}