apiforge-analyzer 1.3.6 → 1.3.8

package/dist/cjs/cli.js

@@ -6,11 +6,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const prompts_1 = require("@clack/prompts");
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
 const child_process_1 = require("child_process");
 const axios_1 = __importDefault(require("axios"));
 const arch_detect_js_1 = require("./arch-detect.js");
 const uploader_js_1 = require("./uploader.js");
+const detect_js_1 = require("./detect.js");
+const python_js_1 = require("./frameworks/python.js");
+const python_introspect_js_1 = require("./frameworks/python-introspect.js");
 // ─── ANSI colour helpers ──────────────────────────────────────────────────────
 const r = '\x1b[0m';
 const b = '\x1b[1m';
@@ -110,6 +114,23 @@ async function main() {
     const isLocal = backendChoice === 'local';
     const backendUrl = isLocal ? BACKEND_LOCAL : BACKEND_PROD;
     const dashboardUrl = isLocal ? DASHBOARD_LOCAL : DASHBOARD_PROD;
+    // ── Python project: routes are read by importing the app, no injection ───
+    const pythonFramework = (0, detect_js_1.detectPythonFramework)(process.cwd());
+    if (pythonFramework) {
+        // Mixed repos (e.g. a Python API with a JS frontend) get to choose
+        const usePython = detectScripts().length === 0 || await (0, prompts_1.confirm)({
+            message: `${PYTHON_LABELS[pythonFramework]} project detected — document the Python API?`,
+            initialValue: true,
+        });
+        if ((0, prompts_1.isCancel)(usePython)) {
+            (0, prompts_1.cancel)('Cancelled.');
+            process.exit(0);
+        }
+        if (usePython) {
+            await pythonFlow(pythonFramework, { projectName, apiKey, baseUrl, backendUrl, dashboardUrl });
+            return;
+        }
+    }
     // ── Detect architecture type ─────────────────────────────────────────────
     const archResult = (0, arch_detect_js_1.detectArchitectureType)(process.cwd());
     const archLabel = {
@@ -772,6 +793,747 @@ async function microservicesFlow(config, opts) {
     }[approval.status];
     (0, prompts_1.outro)(outroMsg);
 }
+// ─── Python flow ──────────────────────────────────────────────────────────────
+const PYTHON_LABELS = {
+    fastapi: 'FastAPI',
+    flask: 'Flask',
+    django: 'Django',
+};
+/**
+ * FastAPI / Flask / Django — same shape as the Node flow: inject a snippet into
+ * the file that defines the app, run the user's chosen start command, collect
+ * the routes it reports, kill the server, upload, then offer to remove the
+ * snippet. If the framework isn't installed, it first offers to create .venv
+ * and pip install the project's dependencies (the `npm install` step). Unlike
+ * the Node snippet, the Python one never uploads and holds no API key: it
+ * writes routes to a temp status file and the CLI uploads them.
+ */
+async function pythonFlow(framework, opts) {
+    const cwd = process.cwd();
+    tryUnlink((0, path_1.join)(cwd, STATUS_FILE));
+    tryUnlink((0, path_1.join)(cwd, LOCK_FILE));
+    // ── Locate the app (FastAPI/Flask) or settings module (Django) ───────────
+    const candidates = (0, python_js_1.findPythonApps)(framework, cwd);
+    let target;
+    if (candidates.length === 1) {
+        target = candidates[0];
+    }
+    else if (candidates.length > 1) {
+        const choice = await (0, prompts_1.select)({
+            message: framework === 'django' ? 'Which Django project?' : `Which ${PYTHON_LABELS[framework]} app?`,
+            options: candidates.map((c, i) => ({ value: i, label: c.label })),
+        });
+        if ((0, prompts_1.isCancel)(choice)) {
+            (0, prompts_1.cancel)('Cancelled.');
+            process.exit(0);
+        }
+        target = candidates[choice];
+    }
+    else {
+        const typed = await (0, prompts_1.text)({
+            message: framework === 'django'
+                ? 'Django settings module'
+                : `Where is your ${PYTHON_LABELS[framework]} app?  ${dim('(module:variable)')}`,
+            placeholder: framework === 'django' ? 'mysite.settings' : 'main:app',
+            validate: v => (!v.trim() ? 'Required' : undefined),
+        });
+        if ((0, prompts_1.isCancel)(typed)) {
+            (0, prompts_1.cancel)('Cancelled.');
+            process.exit(0);
+        }
+        const value = typed.trim();
+        target = framework === 'django'
+            ? { label: value, djangoSettings: value, appDir: cwd }
+            : { label: value, app: value, appDir: cwd };
+    }
+    const entryFile = pythonEntryFile(framework, target) ?? await askPythonEntryFile(framework);
+    const entryLabel = (0, path_1.relative)(cwd, entryFile) || (0, path_1.basename)(entryFile);
+    // ── Python environment: offer to create/install it when the framework is missing ─
+    // The Node flow expects `npm install` to have been run; here we offer to do the
+    // equivalent (venv + pip install) rather than fail on the first ImportError.
+    let pythonPath = projectInterpreter(target.appDir, cwd);
+    if (!pythonCanImport(pythonPath, PYTHON_MODULES[framework], target.appDir)) {
+        pythonPath = await setupPythonEnvironment(framework, pythonPath, target.appDir, cwd);
+    }
+    // ── Which command starts the server ───────────────────────────────────────
+    const runChoice = await (0, prompts_1.select)({
+        message: 'Which command starts your server?',
+        options: [
+            ...pythonRunCommands(framework, target, entryFile, pythonPath).map(c => ({ value: c, label: c })),
+            { value: '__custom', label: 'Enter a command…' },
+        ],
+    });
+    if ((0, prompts_1.isCancel)(runChoice)) {
+        (0, prompts_1.cancel)('Cancelled.');
+        process.exit(0);
+    }
+    let runCommand = runChoice;
+    if (runCommand === '__custom') {
+        const typed = await (0, prompts_1.text)({
+            message: `Command that starts your server  ${dim(`(run from ${(0, path_1.relative)(cwd, target.appDir) || '.'})`)}`,
+            placeholder: 'uvicorn main:app',
+            validate: v => (!v.trim() ? 'Required' : undefined),
+        });
+        if ((0, prompts_1.isCancel)(typed)) {
+            (0, prompts_1.cancel)('Cancelled.');
+            process.exit(0);
+        }
+        runCommand = typed.trim();
+    }
+    prompts_1.log.info(dim('─────────────────────────────────────────────────'));
+    prompts_1.log.info(`${dim('Project:')}       ${bold(opts.projectName)}`);
+    prompts_1.log.info(`${dim('Framework:')}     ${cyan(PYTHON_LABELS[framework])}`);
+    prompts_1.log.info(`${dim(framework === 'django' ? 'Settings:' : 'App:     ')}      ${bold(target.label)}`);
+    prompts_1.log.info(`${dim('Command:')}       ${bold(runCommand)}`);
+    prompts_1.log.info(`${dim('Backend:')}       ${cyan(opts.backendUrl)}`);
+    prompts_1.log.info(dim('─────────────────────────────────────────────────'));
+    // ── Patch entry file, start server, collect routes ───────────────────────
+    // Status + introspection script live in the OS temp dir: nothing besides the
+    // snippet is written into the user's project.
+    const statusPath = (0, path_1.join)((0, os_1.tmpdir)(), `apiforge-${process.pid}-status.json`);
+    const introspectPath = (0, path_1.join)((0, os_1.tmpdir)(), `apiforge-${process.pid}-introspect.py`);
+    const removeTempFiles = () => {
+        tryUnlink(statusPath);
+        tryUnlink(statusPath + '.tmp');
+        tryUnlink(introspectPath);
+    };
+    removeTempFiles();
+    (0, fs_1.writeFileSync)(introspectPath, python_introspect_js_1.PYTHON_INTROSPECT_SCRIPT, 'utf-8');
+    const injection = injectPythonSnippet(entryFile, framework, target);
+    prompts_1.log.info(`${green('✓')} Patched ${bold(entryLabel)}  ${dim(`+${injection.linesAdded} lines`)}`);
+    // Like the Node flow, removal is offered at the end. Ctrl+C can't be
+    // prompted, so an interrupt removes the snippet straight away.
+    const onInterrupt = () => {
+        removePythonSnippet(entryFile, injection.block);
+        removeTempFiles();
+        process.exit(130);
+    };
+    process.on('SIGINT', onInterrupt);
+    const offerCleanup = async () => {
+        process.removeListener('SIGINT', onInterrupt);
+        await offerPythonCleanup(entryFile, entryLabel, injection.block);
+    };
+    const s = (0, prompts_1.spinner)();
+    const venvLabel = (0, path_1.relative)(cwd, pythonPath) || pythonPath;
+    // A server that dies on `No module named 'x'` gets the package installed and
+    // is restarted — the missing-dependency half of `npm install`, done on demand.
+    // Only packages the project declares (or well-known import≠pip names) are
+    // offered, so a missing local module never turns into a random PyPI install.
+    let result;
+    const installedForRun = new Set();
+    let spinning = false;
+    try {
+        for (;;) {
+            s.start('Starting your server and reading its routes…');
+            spinning = true;
+            tryUnlink(statusPath);
+            result = await runPythonServerAndCollect(runCommand, target.appDir, {
+                APIFORGE_INTROSPECT: introspectPath,
+                APIFORGE_STATUS_FILE: statusPath,
+                APIFORGE_FRAMEWORK: framework,
+                ...(target.djangoSettings ? { APIFORGE_DJANGO_SETTINGS: target.djangoSettings } : {}),
+            }, statusPath, 90000);
+            if (result.routes?.length)
+                break;
+            const missing = missingPythonPackage(result.output, pythonPath, target.appDir, cwd);
+            if (!missing || installedForRun.has(missing.requirement) || installedForRun.size >= 15)
+                break;
+            s.stop(yellow(`◌ Your server needs ${bold(missing.requirement)}  ${dim(`(No module named '${missing.module}')`)}`));
+            spinning = false;
+            const install = await (0, prompts_1.confirm)({
+                message: `Install ${missing.requirement} into ${venvLabel} and retry?`,
+                initialValue: true,
+            });
+            if ((0, prompts_1.isCancel)(install) || !install)
+                break;
+            installedForRun.add(missing.requirement);
+            s.start(`Installing ${missing.requirement}…`);
+            const pip = await runCapture(pythonPath, ['-m', 'pip', 'install', '--disable-pip-version-check', missing.requirement], cwd, 10 * 60000);
+            if (pip.code !== 0) {
+                s.stop(red(`✗ pip install ${missing.requirement} failed`));
+                spinning = false;
+                pip.output.split('\n').slice(-15).forEach(line => prompts_1.log.info(dim(`  ${line}`)));
+                break;
+            }
+            s.stop(green(`✓ Installed ${missing.requirement} — retrying`));
+            spinning = false;
+        }
+    }
+    finally {
+        removeTempFiles();
+    }
+    if (result.error || !result.routes?.length) {
+        const failure = red(`✗ ${result.error ?? 'No routes found'}`);
+        if (spinning)
+            s.stop(failure);
+        else
+            prompts_1.log.error(failure);
+        prompts_1.log.warn(yellow('Hint: run the command above yourself first — if it does not start your server, APIForge can\'t either.'));
+        prompts_1.log.warn(yellow(`  1. Dependencies are installed for ${pythonPath}`));
+        prompts_1.log.warn(yellow('  2. Env vars your app reads at startup (DB URL, secrets) are set'));
+        if (result.output) {
+            // Python prints the actual error last — show the end of the output, not the start.
+            prompts_1.log.info('');
+            prompts_1.log.info(dim('─── Server output (last lines) ──────────────────'));
+            result.output.split('\n').slice(-25).forEach(line => prompts_1.log.info(dim(`  ${line}`)));
+            prompts_1.log.info(dim('─────────────────────────────────────────────────'));
+        }
+        await offerCleanup();
+        (0, prompts_1.outro)(red('Analysis failed.'));
+        process.exit(1);
+    }
+    const routes = result.routes ?? [];
+    s.stop(green(`✓ ${routes.length} routes found`));
+    // ── Upload ────────────────────────────────────────────────────────────────
+    const uploadSpin = (0, prompts_1.spinner)();
+    uploadSpin.start(`Uploading ${routes.length} routes…`);
+    const uploadResult = await (0, uploader_js_1.uploadRoutes)(routes, {
+        projectName: opts.projectName,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl,
+        apiForgeUrl: opts.backendUrl,
+        architectureType: 'monolithic',
+    });
+    if (!uploadResult) {
+        uploadSpin.stop(red('✗ Upload failed'));
+        await offerCleanup();
+        (0, prompts_1.outro)(red('Analysis failed.'));
+        process.exit(1);
+    }
+    uploadSpin.stop(green(`✓ ${uploadResult.routeCount} routes submitted to APIForge`));
+    // ── Poll for dashboard approval ───────────────────────────────────────────
+    (0, prompts_1.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 = (0, prompts_1.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') {
+        (0, prompts_1.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') {
+        (0, prompts_1.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 {
+        (0, prompts_1.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');
+    }
+    // ── Cleanup ───────────────────────────────────────────────────────────────
+    await offerCleanup();
+    tryUnlink((0, path_1.join)(cwd, STATUS_FILE));
+    tryUnlink((0, path_1.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];
+    (0, prompts_1.outro)(outroMsg);
+}
+// ─── Python environment ───────────────────────────────────────────────────────
+const PYTHON_MODULES = {
+    fastapi: 'fastapi',
+    flask: 'flask',
+    django: 'django',
+};
+const VENV_PYTHON = process.platform === 'win32'
+    ? (0, path_1.join)('.venv', 'Scripts', 'python.exe')
+    : (0, path_1.join)('.venv', 'bin', 'python');
+/** Interpreter for the app: a venv next to the app wins, then one at the project root. */
+function projectInterpreter(appDir, rootDir) {
+    const fromApp = (0, python_js_1.findPythonInterpreter)(appDir);
+    if ((0, path_1.isAbsolute)(fromApp) || appDir === rootDir)
+        return fromApp;
+    return (0, python_js_1.findPythonInterpreter)(rootDir);
+}
+function pythonCanImport(pythonPath, module, cwd) {
+    try {
+        const r = (0, child_process_1.spawnSync)(pythonPath, ['-c', `import ${module}`], { cwd, stdio: 'ignore', timeout: 30000 });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** A working base interpreter to create a venv with ('python' on Windows is often the Store stub). */
+function basePython() {
+    const candidates = process.platform === 'win32' ? ['py', 'python', 'python3'] : ['python3', 'python'];
+    return candidates.find(c => {
+        try {
+            return (0, child_process_1.spawnSync)(c, ['-c', 'import venv'], { stdio: 'ignore', timeout: 15000 }).status === 0;
+        }
+        catch {
+            return false;
+        }
+    }) ?? null;
+}
+/** Run a command (no shell) and keep the tail of its output for error reporting. */
+function runCapture(cmd, args, cwd, timeoutMs) {
+    return new Promise(resolve => {
+        let output = '';
+        const keepTail = (chunk) => { output = (output + chunk.toString()).slice(-8000); };
+        const child = (0, child_process_1.spawn)(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, PYTHONIOENCODING: 'utf-8' } });
+        child.stdout?.on('data', keepTail);
+        child.stderr?.on('data', keepTail);
+        const timer = setTimeout(() => { if (child.pid)
+            killProcessTree(child.pid); }, timeoutMs);
+        child.on('error', err => { clearTimeout(timer); resolve({ code: null, output: err.message }); });
+        child.on('close', code => { clearTimeout(timer); resolve({ code, output: output.trim() }); });
+    });
+}
+/**
+ * Where the project declares its dependencies, as pip arguments. requirements
+ * files first (closest to the app), then an installable package (setup.py /
+ * pyproject with a build backend), then a bare pyproject's dependency list.
+ */
+function pythonInstallPlan(appDir, rootDir, pythonPath) {
+    for (const dir of unique([appDir, rootDir])) {
+        for (const file of ['requirements.txt', (0, path_1.join)('requirements', 'base.txt'), 'requirements-dev.txt']) {
+            if ((0, fs_1.existsSync)((0, path_1.join)(dir, file))) {
+                return { label: (0, path_1.relative)(rootDir, (0, path_1.join)(dir, file)) || file, args: ['-r', (0, path_1.join)(dir, file)] };
+            }
+        }
+    }
+    const pyproject = (0, path_1.join)(rootDir, 'pyproject.toml');
+    const pyprojectText = (0, fs_1.existsSync)(pyproject) ? (0, fs_1.readFileSync)(pyproject, 'utf-8') : '';
+    if ((0, fs_1.existsSync)((0, path_1.join)(rootDir, 'setup.py')) || (0, fs_1.existsSync)((0, path_1.join)(rootDir, 'setup.cfg')) || /^\[build-system\]/m.test(pyprojectText)) {
+        return { label: `${(0, fs_1.existsSync)((0, path_1.join)(rootDir, 'setup.py')) ? 'setup.py' : 'pyproject.toml'} (pip install -e .)`, args: ['-e', rootDir] };
+    }
+    if (pyprojectText) {
+        // An app (not a package): install [project] / [tool.poetry] dependencies directly.
+        const script = [
+            'import sys, tomllib',
+            'd = tomllib.load(open(sys.argv[1], "rb"))',
+            'deps = list(d.get("project", {}).get("dependencies", []))',
+            'deps += [n for n in d.get("tool", {}).get("poetry", {}).get("dependencies", {}) if n.lower() != "python"]',
+            'print("\\n".join(deps))',
+        ].join('\n');
+        try {
+            const r = (0, child_process_1.spawnSync)(pythonPath, ['-c', script, pyproject], { encoding: 'utf-8', timeout: 30000 });
+            const deps = (r.stdout || '').split(/\r?\n/).map(s => s.trim()).filter(Boolean);
+            if (r.status === 0 && deps.length)
+                return { label: 'pyproject.toml dependencies', args: deps };
+        }
+        catch { }
+    }
+    return null;
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+/**
+ * The framework isn't importable: offer to do the `npm install` equivalent —
+ * create .venv at the project root (unless a venv is already in use) and pip
+ * install the project's declared dependencies into it.
+ */
+async function setupPythonEnvironment(framework, currentPython, appDir, rootDir) {
+    const usingVenv = (0, path_1.isAbsolute)(currentPython);
+    const venvDir = (0, path_1.join)(rootDir, '.venv');
+    const plan0 = pythonInstallPlan(appDir, rootDir, currentPython);
+    (0, prompts_1.note)([
+        `${yellow(`${PYTHON_LABELS[framework]} isn't installed for ${usingVenv ? currentPython : 'any virtualenv in this project'}.`)}`,
+        '',
+        usingVenv
+            ? `${dim('APIForge can install the project\'s dependencies into that environment:')}`
+            : `${dim('APIForge can create')} ${bold('.venv')} ${dim('here and install the project\'s dependencies into it:')}`,
+        `  ${dim('·')} ${plan0 ? bold(plan0.label) : yellow('no requirements.txt / pyproject.toml / setup.py found')}`,
+        '',
+        dim('Same as running pip install yourself — nothing outside the environment changes.'),
+    ].join('\n'), 'Python environment');
+    const proceed = await (0, prompts_1.confirm)({
+        message: usingVenv ? 'Install dependencies now?' : 'Create .venv and install dependencies?',
+        initialValue: true,
+    });
+    if ((0, prompts_1.isCancel)(proceed) || !proceed) {
+        (0, prompts_1.cancel)(dim(`Install your dependencies (e.g. pip install -r requirements.txt), then re-run apiforge.`));
+        process.exit(0);
+    }
+    const s = (0, prompts_1.spinner)();
+    let pythonPath = currentPython;
+    if (!usingVenv) {
+        s.start('Creating .venv…');
+        const base = basePython();
+        if (!base) {
+            s.stop(red('✗ No Python found to create a virtualenv with — install Python 3, then re-run.'));
+            process.exit(1);
+        }
+        const made = await runCapture(base, ['-m', 'venv', venvDir], rootDir, 120000);
+        pythonPath = (0, path_1.join)(rootDir, VENV_PYTHON);
+        if (made.code !== 0 || !(0, fs_1.existsSync)(pythonPath)) {
+            s.stop(red('✗ Could not create .venv'));
+            if (made.output)
+                prompts_1.log.info(dim(made.output.split('\n').slice(-10).join('\n')));
+            process.exit(1);
+        }
+        s.stop(green(`✓ Created .venv  ${dim(`(${base})`)}`));
+    }
+    const plan = pythonInstallPlan(appDir, rootDir, pythonPath);
+    const installs = plan ? [plan] : [{ label: PYTHON_MODULES[framework], args: [PYTHON_MODULES[framework]] }];
+    for (const step of installs) {
+        s.start(`Installing ${step.label}…  ${dim('(this can take a few minutes)')}`);
+        const r = await runCapture(pythonPath, ['-m', 'pip', 'install', '--disable-pip-version-check', ...step.args], rootDir, 15 * 60000);
+        if (r.code !== 0) {
+            s.stop(red(`✗ pip install failed (${step.label})`));
+            prompts_1.log.info(dim('─── pip output (last lines) ─────────────────────'));
+            r.output.split('\n').slice(-20).forEach(line => prompts_1.log.info(dim(`  ${line}`)));
+            prompts_1.log.info(dim('─────────────────────────────────────────────────'));
+            prompts_1.log.warn(yellow(`Fix the error above, then re-run apiforge — it will reuse ${(0, path_1.relative)(rootDir, pythonPath) || pythonPath}.`));
+            process.exit(1);
+        }
+        s.stop(green(`✓ Installed ${step.label}`));
+    }
+    // The FastAPI dev server isn't always a declared dependency.
+    if (framework === 'fastapi' && !pythonCanImport(pythonPath, 'uvicorn', appDir)) {
+        s.start('Installing uvicorn…');
+        const r = await runCapture(pythonPath, ['-m', 'pip', 'install', '--disable-pip-version-check', 'uvicorn'], rootDir, 5 * 60000);
+        s.stop(r.code === 0 ? green('✓ Installed uvicorn') : yellow('◌ Could not install uvicorn — pick another start command'));
+    }
+    if (!pythonCanImport(pythonPath, PYTHON_MODULES[framework], appDir)) {
+        prompts_1.log.error(red(`${PYTHON_LABELS[framework]} still can't be imported with ${pythonPath}.`));
+        prompts_1.log.warn(yellow('Install it into that environment, then re-run apiforge.'));
+        process.exit(1);
+    }
+    return pythonPath;
+}
+/** Import name → pip name, for the common cases where they differ. */
+const PIP_ALIASES = {
+    jose: 'python-jose[cryptography]', jwt: 'PyJWT', dotenv: 'python-dotenv', yaml: 'PyYAML',
+    PIL: 'Pillow', cv2: 'opencv-python', sklearn: 'scikit-learn', bs4: 'beautifulsoup4',
+    dateutil: 'python-dateutil', multipart: 'python-multipart', magic: 'python-magic',
+    environ: 'django-environ', decouple: 'python-decouple', rest_framework: 'djangorestframework',
+    rest_framework_simplejwt: 'djangorestframework-simplejwt', corsheaders: 'django-cors-headers',
+    debug_toolbar: 'django-debug-toolbar', django_filters: 'django-filter', crispy_forms: 'django-crispy-forms',
+    allauth: 'django-allauth', storages: 'django-storages', sorl: 'sorl-thumbnail', haystack: 'django-haystack',
+    psycopg2: 'psycopg2-binary', MySQLdb: 'mysqlclient', Crypto: 'pycryptodome', attr: 'attrs',
+    slugify: 'python-slugify', socketio: 'python-socketio', docx: 'python-docx', OpenSSL: 'pyOpenSSL',
+};
+const normalizePkg = (name) => name.toLowerCase().replace(/[-_.]+/g, '-');
+/** Every requirement the project declares: requirements*.txt plus pyproject deps, extras and groups. */
+function declaredPythonRequirements(pythonPath, appDir, rootDir) {
+    const reqs = [];
+    const reqDir = (0, path_1.join)(rootDir, 'requirements');
+    for (const dir of unique([appDir, rootDir, reqDir])) {
+        let files = [];
+        // requirements*.txt next to the app / at the root; any .txt inside requirements/
+        try {
+            files = (0, fs_1.readdirSync)(dir).filter(f => f.endsWith('.txt') && (dir === reqDir || f.startsWith('requirements')));
+        }
+        catch { }
+        for (const file of files) {
+            try {
+                for (const line of (0, detect_js_1.readTextFile)((0, path_1.join)(dir, file)).split(/\r?\n/)) {
+                    const req = line.split(/\s+#|;/)[0].trim();
+                    if (req && !req.startsWith('#') && !req.startsWith('-'))
+                        reqs.push(req);
+                }
+            }
+            catch { }
+        }
+    }
+    const pyproject = (0, path_1.join)(rootDir, 'pyproject.toml');
+    if ((0, fs_1.existsSync)(pyproject)) {
+        const script = [
+            'import sys, tomllib',
+            'd = tomllib.load(open(sys.argv[1], "rb"))',
+            'p, poetry = d.get("project", {}), d.get("tool", {}).get("poetry", {})',
+            'out = list(p.get("dependencies", []))',
+            'for extra in p.get("optional-dependencies", {}).values(): out += extra',
+            'for group in d.get("dependency-groups", {}).values(): out += [g for g in group if isinstance(g, str)]',
+            'out += [n for n in poetry.get("dependencies", {}) if n.lower() != "python"]',
+            'for group in poetry.get("group", {}).values(): out += list(group.get("dependencies", {}))',
+            'print("\\n".join(out))',
+        ].join('\n');
+        try {
+            const r = (0, child_process_1.spawnSync)(pythonPath, ['-c', script, pyproject], { encoding: 'utf-8', timeout: 30000 });
+            if (r.status === 0)
+                reqs.push(...(r.stdout || '').split(/\r?\n/).map(s => s.split(';')[0].trim()).filter(Boolean));
+        }
+        catch { }
+    }
+    return reqs;
+}
+/**
+ * The pip requirement for a `No module named 'x'` crash, or null when it isn't
+ * safe to guess. Prefers the project's own declaration (keeps its version pins,
+ * and maps e.g. `environ` → `django-environ>=0.4`), then PIP_ALIASES.
+ */
+function missingPythonPackage(output, pythonPath, appDir, rootDir) {
+    // FastAPI raises RuntimeError, not ModuleNotFoundError, for form/file params.
+    if (/python-multipart/.test(output) && /Form data requires|File uploads require/.test(output)) {
+        return { module: 'multipart', requirement: 'python-multipart' };
+    }
+    const matches = [...output.matchAll(/ModuleNotFoundError: No module named '([\w.]+)'/g)];
+    if (!matches.length)
+        return null;
+    const module = matches[matches.length - 1][1].split('.')[0];
+    const wanted = normalizePkg(module);
+    const declared = declaredPythonRequirements(pythonPath, appDir, rootDir)
+        .map(req => ({ req, name: normalizePkg(req.match(/^[A-Za-z0-9][A-Za-z0-9._-]*/)?.[0] ?? '') }))
+        .filter(d => d.name);
+    const hit = declared.find(d => d.name === wanted)
+        ?? declared.find(d => d.name.endsWith(`-${wanted}`) || d.name.startsWith(`${wanted}-`));
+    if (hit)
+        return { module, requirement: hit.req };
+    if (PIP_ALIASES[module])
+        return { module, requirement: PIP_ALIASES[module] };
+    return null;
+}
+/** Node-flow parity: ask before removing the snippet (it's inert if kept). */
+async function offerPythonCleanup(entryFile, entryLabel, block) {
+    const shouldClean = await (0, prompts_1.confirm)({
+        message: `Remove APIForge code changes from ${bold(entryLabel)}?`,
+        initialValue: true,
+    });
+    if ((0, prompts_1.isCancel)(shouldClean) || !shouldClean) {
+        prompts_1.log.info(dim(`Left in ${entryLabel} — it does nothing unless the APIForge CLI runs it, and the next run replaces it.`));
+        return;
+    }
+    if (removePythonSnippet(entryFile, block)) {
+        prompts_1.log.success(green(`✓ Removed code changes from ${entryLabel}`));
+    }
+    else {
+        prompts_1.log.warn(yellow(`Could not auto-remove — please delete the APIForge block from ${entryLabel} manually.`));
+    }
+}
+// stripPythonSnippet() matches on the "# APIForge — temporary" prefix — keep it stable.
+const PY_SNIPPET_START = '# APIForge — temporary analysis snippet, safe to delete';
+const PY_SNIPPET_END = '# /APIForge';
+const PY_MAIN_GUARD = /^if\s+__name__\s*==\s*['"]__main__['"]\s*:/m;
+/** The file the snippet goes into: the module defining the app, or Django's manage.py. */
+function pythonEntryFile(framework, target) {
+    if (target.file && (0, fs_1.existsSync)(target.file))
+        return target.file;
+    if (framework === 'django') {
+        const manage = (0, path_1.join)(target.appDir, 'manage.py');
+        return (0, fs_1.existsSync)(manage) ? manage : null;
+    }
+    // Typed by hand: derive it from "module:app".
+    const dotted = target.app?.split(':')[0];
+    if (!dotted)
+        return null;
+    const base = (0, path_1.join)(target.appDir, ...dotted.split('.'));
+    return [`${base}.py`, (0, path_1.join)(base, '__init__.py')].find(f => (0, fs_1.existsSync)(f)) ?? null;
+}
+async function askPythonEntryFile(framework) {
+    const resolve = (p) => ((0, path_1.isAbsolute)(p) ? p : (0, path_1.join)(process.cwd(), p));
+    const typed = await (0, prompts_1.text)({
+        message: framework === 'django' ? 'Path to your manage.py' : 'Path to the file that creates your app',
+        placeholder: framework === 'django' ? 'manage.py' : 'main.py',
+        validate: v => {
+            if (!v.trim())
+                return 'Required';
+            if (!(0, fs_1.existsSync)(resolve(v.trim())))
+                return `Not found: ${v.trim()}`;
+        },
+    });
+    if ((0, prompts_1.isCancel)(typed)) {
+        (0, prompts_1.cancel)('Cancelled.');
+        process.exit(0);
+    }
+    return resolve(typed.trim());
+}
+/**
+ * Every usual way to start each framework's dev server, using the interpreter
+ * that has the project's dependencies — the Python counterpart of listing
+ * package.json scripts. Commands run from target.appDir.
+ */
+function pythonRunCommands(framework, target, entryFile, pythonPath) {
+    const py = `"${pythonPath}"`;
+    const relFile = (0, path_1.relative)(target.appDir, entryFile);
+    let source = '';
+    try {
+        source = (0, fs_1.readFileSync)(entryFile, 'utf-8');
+    }
+    catch { }
+    // The file starts its own server: `if __name__ == "__main__": uvicorn.run(app)` / app.run()
+    const runsItself = PY_MAIN_GUARD.test(source);
+    if (framework === 'django') {
+        return [
+            `${py} manage.py runserver --noreload`,
+            `${py} manage.py runserver`,
+        ];
+    }
+    if (framework === 'fastapi') {
+        const app = target.app ?? 'main:app';
+        const factory = target.factory ? ' --factory' : '';
+        const commands = [];
+        // `fastapi dev` is FastAPI's own recommended command (and the only one that
+        // sets FASTAPI_ENV=development) — list it first when fastapi-cli is installed.
+        if (!target.factory && pythonCanImport(pythonPath, 'fastapi_cli', target.appDir)) {
+            commands.push(`${py} -m fastapi dev ${relFile}`, `${py} -m fastapi run ${relFile}`);
+        }
+        commands.push(`${py} -m uvicorn ${app}${factory}`);
+        if (runsItself)
+            commands.push(`${py} ${relFile}`);
+        return commands;
+    }
+    const commands = [`${py} -m flask --app ${target.app ?? 'app'} run`];
+    if (runsItself)
+        commands.push(`${py} ${relFile}`);
+    return commands;
+}
+/**
+ * The snippet is inert unless APIFORGE_INTROSPECT is set — only the CLI sets
+ * it — so a copy left behind by a hard-killed run can't do anything.
+ * Factories (Flask create_app, uvicorn --factory) are wrapped so the routes are
+ * read from the app the factory returns.
+ */
+function buildPythonSnippet(appAttr, factory) {
+    const run = (appExpr, indent) => [
+        `${indent}with open(_apiforge_os.environ["APIFORGE_INTROSPECT"], encoding="utf-8") as _apiforge_fh:`,
+        `${indent}    exec(_apiforge_fh.read(), {"__name__": "apiforge_introspect", "APIFORGE_APP": ${appExpr}})`,
+    ];
+    const body = factory && appAttr
+        ? [
+            `    _apiforge_factory = ${appAttr}`,
+            `    def ${appAttr}(*args, **kwargs):`,
+            `        _apiforge_app = _apiforge_factory(*args, **kwargs)`,
+            ...run('_apiforge_app', '        '),
+            `        return _apiforge_app`,
+        ]
+        : run(appAttr ?? 'None', '    ');
+    return [
+        PY_SNIPPET_START,
+        `# https://apiforge.brainfogagency.com — does nothing unless run by the APIForge CLI`,
+        `import os as _apiforge_os`,
+        `if _apiforge_os.environ.get("APIFORGE_INTROSPECT"):`,
+        ...body,
+        PY_SNIPPET_END,
+    ];
+}
+/**
+ * Insert the snippet after the app is built: before an `if __name__ == "__main__":`
+ * block (which would otherwise start the server first), else at the end of the
+ * file. Django's manage.py gets it before the command runs; the snippet then sets
+ * Django up itself. Returns the exact inserted text so removal restores the file
+ * byte-for-byte.
+ */
+function injectPythonSnippet(filePath, framework, target) {
+    // A previous run that was hard-killed before cleanup: drop its block first.
+    const content = stripPythonSnippet((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const appAttr = framework === 'django' ? null : (target.app?.split(':')[1] || 'app');
+    const factory = !!target.factory || (!!appAttr && new RegExp(`^def\\s+${appAttr}\\s*\\(`, 'm').test(content));
+    const lines = buildPythonSnippet(appAttr, factory);
+    const snippet = lines.join(eol) + eol;
+    // manage.py without a __main__ guard runs the command at top level; go before that call.
+    const guard = PY_MAIN_GUARD.exec(content)
+        ?? (framework === 'django' ? /^execute_from_command_line\s*\(/m.exec(content) : null);
+    let block;
+    let next;
+    if (guard) {
+        block = snippet + eol;
+        next = content.slice(0, guard.index) + block + content.slice(guard.index);
+    }
+    else {
+        block = (content === '' || content.endsWith('\n') ? '' : eol) + eol + snippet;
+        next = content + block;
+    }
+    (0, fs_1.writeFileSync)(filePath, next, 'utf-8');
+    return { block, linesAdded: lines.length };
+}
+function removePythonSnippet(filePath, block) {
+    try {
+        const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        const cleaned = block && content.includes(block)
+            ? content.replace(block, () => '')
+            : stripPythonSnippet(content);
+        if (cleaned !== content)
+            (0, fs_1.writeFileSync)(filePath, cleaned, 'utf-8');
+        return !cleaned.includes(PY_SNIPPET_START);
+    }
+    catch {
+        return false;
+    }
+}
+function stripPythonSnippet(content) {
+    return content.replace(/(?:\r?\n)?# APIForge — temporary[^\n]*\r?\n[\s\S]*?# \/APIForge\r?\n?/g, '');
+}
+/**
+ * Run the user's start command and wait for the injected snippet to write the
+ * status file. The server is killed as soon as routes arrive — before it would
+ * normally even bind its port, since every supported server loads the app first.
+ */
+function runPythonServerAndCollect(command, cwd, env, statusPath, timeoutMs) {
+    return new Promise(resolve => {
+        const child = (0, child_process_1.spawn)(command, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: true,
+            env: { ...process.env, ...env, PYTHONDONTWRITEBYTECODE: '1', PYTHONIOENCODING: 'utf-8' },
+        });
+        // Tail-capped, unlike the Node flow: a Python traceback ends with the real error.
+        let output = '';
+        const capture = (chunk) => { output = (output + chunk.toString()).slice(-12000); };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(poller);
+            clearTimeout(timer);
+            if (child.pid)
+                killProcessTree(child.pid);
+            resolve({ ...r, output: output.trim() });
+        };
+        const readStatus = () => {
+            try {
+                if (!(0, fs_1.existsSync)(statusPath))
+                    return false;
+                const data = JSON.parse((0, fs_1.readFileSync)(statusPath, 'utf-8'));
+                if (data.status === 'collected' && Array.isArray(data.routes)) {
+                    finish({ routes: data.routes });
+                    return true;
+                }
+                if (data.status === 'error') {
+                    finish({ error: data.error || 'Route collection failed' });
+                    return true;
+                }
+            }
+            catch { }
+            return false;
+        };
+        const poller = setInterval(readStatus, 500);
+        const timer = setTimeout(() => finish({
+            error: `Timed out after ${Math.round(timeoutMs / 1000)}s — the server never loaded the app`,
+        }), timeoutMs);
+        child.on('error', err => finish({ error: err.message }));
+        child.on('exit', code => {
+            // The status file can land just before the server dies (e.g. port already in use).
+            setTimeout(() => {
+                if (!readStatus())
+                    finish({ error: `Server exited (code ${code}) before routes were collected` });
+            }, 600);
+        });
+    });
+}
 // ─── Server subprocess ────────────────────────────────────────────────────────
 /**
  * Kill the whole process tree rooted at `pid`, not just that one process.