codetac 0.1.0 → 0.2.0

package/src/cli.mjs

@@ -5,24 +5,27 @@
 //   codetac [pasta] [opções] [-- comando de arranque]
 //   codetac diagnostico [pasta]
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { arch, homedir, release } from 'node:os';
 import http from 'node:http';
 import { basename, join, resolve } from 'node:path';
 import readline from 'node:readline/promises';
 import { pathToFileURL } from 'node:url';
 import { detectProject, describeStart, foreignRuntime } from './detect.mjs';
+import { MINIMUM, commandFor, describePythonFolder, environmentOf, interpreters, moveTo, probe, proxyOf, pythonPort, versionBelow } from './detect-python.mjs';
 import { createSummary, follow } from './recording.mjs';
 
 import { dataDirectory, install as workspace } from './home.mjs';
 
 const recordings = dataDirectory();
 const register = pathToFileURL(join(workspace, 'src', 'register.mjs')).href;
+// The Python captor: its sitecustomize.py runs in every Python process of the app.
+const captor = join(workspace, 'src', 'python', 'codetac_py');
 const started = Date.now();
 const seconds = () => `${Math.round((Date.now() - started) / 1000)} s`;
 const say = text => process.stdout.write(`${text}\n`);
 const HELP = `Uso:
-  codetac [pasta] [opções] [-- comando]   arranca a app da pasta (por omissão, a atual) com o CodeTAC
+  codetac [pasta] [opções] [-- comando]   arranca a app da pasta (por omissão, a atual) com o CodeTAC: Node ou Python (FastAPI, Flask)
   codetac diagnostico [pasta]              explica o que está e o que não está a funcionar
   codetac relatorio [pasta]                guarda o diagnóstico num ficheiro para enviar com uma incidência
   codetac --version                        versão instalada
@@ -33,7 +36,7 @@ Opções:
   --porta <n>          porta da app, se não for descoberta sozinha
   --painel <n>         porta do painel (por omissão 4000)
   --minimo             não seguir as funções do projeto (só pedidos e fronteiras)
-  --sim                responder «sim» às perguntas (instalar dependências…)
+  --sim                responder «sim» às perguntas (instalar dependências, criar o .venv…)
   --nao-abrir          não abrir o browser
   -- <comando>         comando de arranque, quando não for descoberto (ex.: -- node server.js)`;
 
@@ -156,14 +159,20 @@ function startApp(parts, { run, panelPort, minimal, reason, root, extraEnv = {}
   const env = {
     ...process.env, CODETAC_ROOT: root, CODETAC_RUN: run, CODETAC_PANEL_PORT: String(panelPort),
     NODE_OPTIONS: [process.env.NODE_OPTIONS, `--import=${register}`].filter(Boolean).join(' '),
+    PYTHONPATH: [captor, process.env.PYTHONPATH].filter(Boolean).join(process.platform === 'win32' ? ';' : ':'),
   };
+  // Python writes to a pipe in blocks: without this, the app's prints would show late.
+  env.PYTHONUNBUFFERED ??= '1';
+  // Python's bytecode (__pycache__) goes to CodeTAC's folder, not into the project:
+  // some projects even keep .pyc files in Git.
+  env.PYTHONPYCACHEPREFIX ??= join(recordings, 'pycache');
   // The application's output goes through a pipe: its colours stay when the terminal has them.
   if (process.stdout.isTTY && env.FORCE_COLOR === undefined) env.FORCE_COLOR = '1';
   Object.assign(env, extraEnv);
   if (minimal) Object.assign(env, { CODETAC_LEVEL: 'minimo', CODETAC_MINIMO_MOTIVO: reason });
   for (const part of parts) {
     const [bin, ...args] = runnable(part.command);
-    const child = spawn(bin, args, { cwd: part.folder, env, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32',
+    const child = spawn(bin, args, { cwd: part.folder, env: { ...env, ...part.env, ...(part.language === 'python' ? environmentOf(part) : {}) }, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32',
       shell: process.platform === 'win32' });
     const label = parts.length > 1 ? `[${part.part}] ` : '';
     const show = chunk => {
@@ -176,6 +185,9 @@ function startApp(parts, { run, panelPort, minimal, reason, root, extraEnv = {}
         for (const match of plain.matchAll(URL_IN_OUTPUT)) if (match[1]) ports.push(Number(match[1]));
         // Watch modes (node --watch, nodemon, tsx watch) keep running after a crash.
         if (CRASHED.test(plain)) child.crashed = true;
+        // A Python app that fails while importing, under a reloader (uvicorn --reload,
+        // fastapi dev, flask --debug): the reloader stays, waiting for changes.
+        if (child.part?.language === 'python' && /^\s*Traceback \(most recent call last\):/.test(plain)) child.tracebackAt ??= Date.now();
         const busy = plain.match(BUSY);
         if (busy) state.busy = Number(busy[1] ?? busy[2] ?? busy[3]);
       }
@@ -199,9 +211,11 @@ function freePort() {
   });
 }
 
-function stopAll(children, signal = 'SIGTERM') {
+function stopAll(children, force = null) {
   for (const child of children) {
     if (child.exitCode !== null || child.signalCode !== null) continue;
+    // Python apps stop as with Ctrl+C: SIGTERM makes some of them warn (leaked semaphores).
+    const signal = force ?? (child.part?.language === 'python' ? 'SIGINT' : 'SIGTERM');
     try { process.platform === 'win32' ? child.kill(signal) : process.kill(-child.pid, signal); } catch { try { child.kill(signal); } catch {} }
   }
 }
@@ -250,7 +264,8 @@ async function findApp(candidates, panelPort, { children, addresses, warn }) {
       if (others.length) {
         // Reach the application by the exact address it bound.
         const bound = addresses.get(port) ?? (mine[0].names.find(name => /^127\.0\.0\.1:|^\[::1\]:/.test(name)) ?? mine[0].names[0] ?? '').replace(/:\d+$/, '');
-        host = /^\[?::1\]?$/.test(bound) ? '::1' : '127.0.0.1';
+        // '::' (every IPv6 address) too: the other program holds the IPv4 one.
+        host = /^\[?::1?\]?$/.test(bound) ? '::1' : '127.0.0.1';
         warn(port, others[0].command ?? 'outro programa', host);
       }
     }
@@ -268,6 +283,131 @@ async function findApp(candidates, panelPort, { children, addresses, warn }) {
   return api;
 }
 
+// DP5: a Python project without an environment, or without its dependencies.
+// Always asked first (--sim answers yes); the environment is .venv in the project.
+function requirementFiles(folder) {
+  let names = [];
+  try { names = readdirSync(folder); } catch {}
+  const files = names.filter(name => /^requirements.*\.txt$/.test(name) && !/(dev|test|lint|doc)/.test(name));
+  return files.includes('requirements.txt') ? ['requirements.txt'] : files.slice(0, 1);
+}
+function pythonSteps(part, { create, skip = [] }) {
+  const { folder, python } = part;
+  const uv = hasBinary('uv');
+  const venvPython = python.interpreter ?? join(folder, '.venv', process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python');
+  const steps = [];
+  let chosen = null;
+  if (part.manager === 'uv' && uv) return { steps: [['uv', ['sync']]], chosen, env: {} };
+  if (part.manager === 'poetry' || part.manager === 'pipenv') {
+    const tool = part.manager;
+    if (!hasBinary(tool)) return { problem: `O projeto usa o ${tool}, que não está instalado neste computador. Instale-o (por exemplo, pipx install ${tool}) e volte a correr o comando.` };
+    // Both keep the environment in the project when asked to: the .venv of DP5.
+    const env = tool === 'poetry' ? { POETRY_VIRTUALENVS_IN_PROJECT: 'true' } : { PIPENV_VENV_IN_PROJECT: '1' };
+    return { steps: [tool === 'poetry' ? ['poetry', ['install', '--no-root']] : ['pipenv', ['install', '--dev']]], chosen, env };
+  }
+  if (create) {
+    const found = interpreters();
+    chosen = found.find(item => !versionBelow(item.version) && !skip.includes(item.executable)) ?? null;
+    // uv fetches a Python 3.12 when there is none on the computer.
+    if (uv) steps.push(['uv', ['venv', '--python', chosen?.executable ?? MINIMUM.join('.'), '.venv']]);
+    else {
+      chosen ??= found[0] ?? null;
+      if (!chosen) return { problem: 'Não encontrei nenhum Python neste computador. Instale o Python 3.12 ou mais recente (python.org ou brew install python) e volte a correr o comando.' };
+      steps.push([chosen.executable, ['-m', 'venv', '.venv']]);
+    }
+  }
+  const files = requirementFiles(folder);
+  const install = uv ? ['uv', ['pip', 'install', '--python', venvPython]] : [venvPython, ['-m', 'pip', 'install']];
+  if (files.length) steps.push([install[0], [...install[1], '-r', files[0]]]);
+  else if (existsSync(join(folder, 'pyproject.toml'))) {
+    if (uv) steps.push([install[0], [...install[1], '-r', 'pyproject.toml']]);
+    else steps.push({ pyproject: true, install });
+  }
+  return { steps, chosen, env: {} };
+}
+// A command as the user would type it in the project's folder.
+const shown = ([bin, args], folder) => [bin, ...args].map(token => token.startsWith(`${folder}/`) ? token.slice(folder.length + 1) : token)
+  .map(token => token.includes(' ') ? `"${token}"` : token).join(' ');
+
+async function preparePython(part, root, options, skip = []) {
+  const label = part.part === '.' ? 'O projeto' : `A parte ${part.part}`;
+  const create = !part.python.interpreter;
+  const plan = pythonSteps(part, { create, skip });
+  if (plan.problem) { say(`✗ ${label} não tem ambiente Python. ${plan.problem}`); process.exit(2); }
+  const lines = plan.steps.map(step => step.pyproject ? `${shown(step.install, part.folder)} <dependências do pyproject.toml>` : shown(step, part.folder));
+  const why = create
+    ? `${label} não tem ambiente Python (.venv).`
+    : `Faltam dependências no ambiente ${part.python.source} (${part.python.missing.slice(0, 6).join(', ')}${part.python.missing.length > 6 ? '…' : ''}).`;
+  say(`${why} Para arrancar, é preciso correr na pasta ${part.folder}:`);
+  for (const line of lines) say(`    ${line}`);
+  if (create && plan.chosen) say(`  (com o Python ${plan.chosen.version}${skip.length ? '' : ', o mais recente deste computador'})`);
+  else if (create && hasBinary('uv') && part.manager !== 'uv') say(`  (o uv descarrega o Python ${MINIMUM.join('.')}: não há nenhum ${MINIMUM.join('.')} ou mais recente neste computador)`);
+  if (!lines.length) return part;
+  // A retry with an older Python was already agreed to.
+  const yes = skip.length ? true : await confirm(create ? 'Criar o .venv e instalar as dependências agora?' : 'Instalar agora?', options);
+  if (yes === null) { say('Corra esses comandos, ou use --sim para o CodeTAC os correr.'); process.exit(2); }
+  if (!yes) { say('Sem as dependências, a app não arranca. Corra esses comandos e volte a correr o codetac.'); process.exit(2); }
+  for (const step of plan.steps) {
+    let command = step;
+    if (step.pyproject) {
+      const venvPython = join(part.folder, '.venv', process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python');
+      const declared = probe(existsSync(venvPython) ? venvPython : step.install[0], part.folder)?.pyproject ?? [];
+      if (!declared.length) continue;
+      command = [step.install[0], [...step.install[1], ...declared]];
+    }
+    say(`  A correr: ${shown(command, part.folder)}`);
+    // Not the environment of whoever runs codetac: the project's.
+    const env = { ...process.env, ...plan.env };
+    delete env.VIRTUAL_ENV;
+    const result = spawnSync(command[0], command[1], { cwd: part.folder, stdio: 'inherit', env });
+    if (result.status !== 0) {
+      // Pinned dependencies may not exist yet for the newest Python (no wheel, and the
+      // build fails): the new .venv is made again with the next older Python ≥ the minimum.
+      const older = create && plan.chosen ? interpreters().find(item => !versionBelow(item.version) && item.executable !== plan.chosen.executable
+        && ![...skip, plan.chosen.executable].includes(item.executable) && item.version.split('.').slice(0, 2).join('.') !== plan.chosen.version.split('.').slice(0, 2).join('.')) : null;
+      if (older) {
+        say(`! A instalação falhou com o Python ${plan.chosen.version} (algumas dependências fixadas ainda não existem para ele). Vou tentar com o Python ${older.version}.`);
+        rmSync(join(part.folder, '.venv'), { recursive: true, force: true });
+        return preparePython(part, root, options, [...skip, plan.chosen.executable]);
+      }
+      say(`✗ Falhou (código ${result.status}). Veja as mensagens acima.`);
+      process.exit(1);
+    }
+  }
+  if (create && existsSync(join(part.folder, '.venv'))) {
+    const inGit = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: part.folder, encoding: 'utf8' }).stdout?.trim() === 'true';
+    // Git shows the .venv (as untracked) only when nothing ignores it; uv puts a .gitignore inside it.
+    if (inGit && spawnSync('git', ['status', '--porcelain', '--', '.venv'], { cwd: part.folder, encoding: 'utf8' }).stdout.trim()) {
+      say('! O .venv não está no .gitignore. Acrescente a linha «.venv/» ao .gitignore, para não o enviar para o repositório.');
+    }
+  }
+  const again = describePythonFolder(part.folder, root);
+  if (!again?.command) { say('✗ Depois da instalação, continuo sem saber como arrancar a app.'); process.exit(1); }
+  if (again.python.missing.length) say(`! Continuam em falta: ${again.python.missing.join(', ')}. Vou tentar arrancar na mesma.`);
+  return { ...again, part: part.part };
+}
+
+// A command given by the user. In a Python project it runs with the project's
+// environment (uvicorn, flask… as python -m with its interpreter).
+function manualPart(project, root, command) {
+  const top = project.top?.language === 'python' && project.top.folder === root ? project.top : null;
+  if (!top) return { folder: root, part: '.', name: project.name, command, script: null, stack: null, port: null, installed: true, foreign: foreignRuntime(command.join(' ')) };
+  const text = command.join(' ');
+  const part = { ...top, installed: true, notes: [], python: { ...top.python, declared: text, declaredSource: 'o comando indicado' },
+    script: { name: 'o comando indicado', command: text } };
+  part.port = pythonPort(root, { command: text, app: top.python.app });
+  part.command = commandFor(part, part.port?.value ?? 8000);
+  return part;
+}
+
+// The macOS AirPlay Receiver listens on 5000 (and 7000): Flask's default port.
+function portTakenBy(port, who) {
+  if (process.platform === 'darwin' && port === 5000 && /ControlCe|AirPlay/i.test(who ?? '')) {
+    return 'pelo Recetor AirPlay do macOS (ControlCenter). Para voltar a usar a 5000, desligue o «Recetor AirPlay» em Definições do Sistema › Geral › AirDrop e Handoff';
+  }
+  return `por outro programa (${who ?? 'desconhecido'})`;
+}
+
 async function main() {
   const options = parseArgs(process.argv.slice(2));
   if (options.sub === 'ajuda') { say(HELP); return; }
@@ -306,7 +446,7 @@ async function main() {
   const project = detectProject(root);
   let parts = project.start;
   if (options.command?.length) {
-    parts = [{ folder: root, part: '.', name: project.name, command: options.command, script: null, stack: null, port: null, installed: true, foreign: foreignRuntime(options.command.join(' ')) }];
+    parts = [manualPart(project, root, options.command)];
   } else if (options.parts.length) {
     parts = options.parts.map(name => project.parts.find(part => part.part === name || basename(part.folder) === name) ?? (name === '.' ? project.top : null)).filter(Boolean);
     if (!parts.length) { say(`Não encontrei a parte ${options.parts.join(', ')}. Partes: ${project.parts.map(part => part.part).join(', ') || 'nenhuma'}.`); process.exit(2); }
@@ -322,33 +462,89 @@ async function main() {
     if (answer === null) parts = project.parts;
     else parts = answer ? answer.split(/[\s,]+/).map(n => project.parts[Number(n) - 1]).filter(Boolean) : project.parts;
   }
+  if (!parts.length && project.top?.language === 'python') {
+    say(project.top.python.django
+      ? 'Este projeto usa o Django, que o CodeTAC ainda não suporta (só FastAPI e Flask).'
+      : 'Encontrei um projeto Python, mas não a app: procurei FastAPI(...) e Flask(...) nos ficheiros .py e comandos no Procfile, Makefile e README.');
+  }
   if (!parts.length) {
-    say(project.missing.includes('package')
+    const python = project.top?.language === 'python';
+    if (!python) say(project.missing.includes('package')
       ? 'Não encontrei um package.json nem um ficheiro de servidor (server.js, index.js…) nesta pasta.'
       : 'Não encontrei um script de arranque (dev, start…) no package.json.');
-    const answer = await ask('Que comando arranca a app? (ex.: node server.js, ou Enter para sair)');
-    if (!answer) { say('Indique o comando depois de --, por exemplo: codetac . -- node server.js'); process.exit(2); }
-    parts = [{ folder: root, part: '.', name: project.name, command: answer.split(/\s+/), script: null, stack: null, port: null, installed: true, foreign: foreignRuntime(answer) }];
+    const example = python ? 'uvicorn main:app --reload' : 'node server.js';
+    const answer = await ask(`Que comando arranca a app? (ex.: ${example}, ou Enter para sair)`);
+    if (!answer) { say(`Indique o comando depois de --, por exemplo: codetac . -- ${example}`); process.exit(2); }
+    parts = [manualPart(project, root, answer.split(/\s+/))];
   }
-  for (const part of parts) say(`  Arranque: ${describeStart(part)}`);
   for (const part of parts.filter(part => part.foreign)) {
-    say(`! [${part.part}] O script usa ${part.foreign}, que não é o Node: essa parte corre, mas o CodeTAC não a consegue observar por dentro.`);
+    // Python started from a Node script inherits the Python captor (PYTHONPATH).
+    if (/^(python3?|uvicorn)$/.test(part.foreign)) say(`! [${part.part}] O script arranca Python: o CodeTAC observa-o se esse Python for o ${MINIMUM.join('.')} ou mais recente.`);
+    else say(`! [${part.part}] O script usa ${part.foreign}, que não é o Node: essa parte corre, mas o CodeTAC não a consegue observar por dentro.`);
   }
 
-  // 2. Dependencies.
-  for (const part of parts.filter(part => !part.installed)) {
+  // 2. Dependencies. Python (DP5): an environment in the project, always asked first.
+  for (const [index, part] of parts.entries()) {
+    if (part.language === 'python' && !part.installed) parts[index] = await preparePython(part, root, options);
+  }
+  for (const part of parts) say(`  Arranque: ${describeStart(part)}`);
+  for (const part of parts) for (const note of part.notes ?? []) say(`! ${parts.length > 1 ? `[${part.part}] ` : ''}${note}`);
+  for (const part of parts.filter(part => part.language !== 'python' && !part.installed)) {
     const manager = part.manager === 'bun' ? 'npm' : part.manager;
     const where = part.installFolder ?? (part.manager === 'pnpm' || part.workspaces ? root : part.folder);
-    const yes = await confirm(`As dependências de ${part.part === '.' ? 'o projeto' : part.part} não estão instaladas. Instalar agora com «${manager} install»?`, options);
-    if (yes === null) { say(`As dependências não estão instaladas. Corra «${manager} install» na pasta ou use --sim.`); process.exit(2); }
+    // npm: the project's files stay as they are. With a lockfile, `npm ci` installs exactly it;
+    // without one (or when it is out of date), `npm install --no-package-lock` writes none.
+    const locked = manager === 'npm' && existsSync(join(where, 'package-lock.json'));
+    const commands = manager !== 'npm' ? [[manager, 'install']] : locked ? [['npm', 'ci'], ['npm', 'install', '--no-package-lock']] : [['npm', 'install', '--no-package-lock']];
+    const yes = await confirm(`As dependências de ${part.part === '.' ? 'o projeto' : part.part} não estão instaladas. Instalar agora com «${commands[0].join(' ')}»?`, options);
+    if (yes === null) { say(`As dependências não estão instaladas. Corra «${commands[0].join(' ')}» na pasta ou use --sim.`); process.exit(2); }
     if (!yes) continue;
-    const [bin, ...args] = runnable([manager, 'install']);
-    say(`  A instalar (${bin} ${args.join(' ')})…`);
-    const result = spawnSync(bin, args, { cwd: where, stdio: 'inherit', shell: process.platform === 'win32' });
+    let result = null;
+    for (const [index, command] of commands.entries()) {
+      const [bin, ...args] = runnable(command);
+      if (index) say(`! O «${commands[index - 1].join(' ')}» falhou (o package-lock.json não corresponde ao package.json?). Tento sem o lockfile, sem o alterar.`);
+      say(`  A instalar (${bin} ${args.join(' ')})…`);
+      result = spawnSync(bin, args, { cwd: where, stdio: 'inherit', shell: process.platform === 'win32' });
+      if (result.status === 0) break;
+    }
     if (result.status !== 0) { say(`✗ A instalação falhou (código ${result.status}). Veja as mensagens acima.`); process.exit(1); }
     for (const other of parts) if ((other.installFolder ?? other.folder) === where || (where === root && !other.installFolder)) other.installed = true;
   }
 
+  // A Python app gets its port on the command line: a port another program
+  // holds (AirPlay on 5000, another API on 8000) is replaced before starting.
+  // A Vite proxy that reads the API's port from a variable follows it.
+  const extraEnv = {};
+  for (const [index, part] of parts.entries()) {
+    const old = part.port?.value;
+    if (part.language !== 'python' || !old || options.command?.length) continue;
+    const owners = listeners(old);
+    if (!owners?.length) continue;
+    const who = owners[0].command;
+    const proxies = parts.filter(other => other.language !== 'python').map(other => ({ other, proxy: proxyOf(other.folder, other.script?.command) })).filter(item => item.proxy);
+    const fixed = proxies.find(item => item.proxy.literal.includes(old) && !item.proxy.variables.some(variable => variable.port === old));
+    if (fixed) {
+      say(`✗ A porta ${old}, da API, já está ocupada ${portTakenBy(old, who)}.`);
+      say(`  O proxy do Vite em ${fixed.other.part} envia os pedidos para essa porta, escrita no vite.config: se eu mudasse a API de porta, os pedidos iriam para esse programa.`);
+      say('  Feche esse programa, ou mude a porta no vite.config e no arranque da API, e volte a correr o comando.');
+      process.exit(1);
+    }
+    const port = await freePort();
+    const variable = proxies.flatMap(item => item.proxy.variables).find(item => item.port === old);
+    parts[index] = moveTo(part, port);
+    if (variable) extraEnv[variable.variable] = String(port);
+    say(`! A porta ${old} já está ocupada ${portTakenBy(old, who)}.`);
+    say(`  Vou arrancar ${parts.length > 1 ? `a parte ${part.part}` : 'a app'} na porta ${port}${variable ? `, e o proxy do Vite segue-a (variável ${variable.variable})` : ''}.`);
+    say(`  Arranque: ${describeStart(parts[index])}`);
+  }
+  // Frontend and Python API without a proxy: requests go to another origin (DP3).
+  if (parts.some(part => part.language === 'python')) {
+    for (const part of parts.filter(part => part.stack === 'Vite' && !proxyOf(part.folder, part.script?.command))) {
+      say(`! [${part.part}] O Vite não tem proxy para a API: os pedidos do browser à API vão para outra origem, e o CodeTAC liga-os por aproximação («ligação provável»).`);
+      say('  Para uma ligação exata, configure server.proxy no vite.config.');
+    }
+  }
+
   // 3. The panel, on a port the application does not use.
   const predicted = new Set(parts.map(part => part.port?.value).filter(Boolean));
   if (options.port) predicted.add(options.port);
@@ -375,7 +571,6 @@ async function main() {
   process.on('SIGINT', stop);
   process.on('SIGTERM', stop);
 
-  const extraEnv = {};
   const busyTried = new Set();
   const warnedShared = new Set();
   const sharedWarning = (port, command, host) => {
@@ -393,7 +588,9 @@ async function main() {
     let warned = false;
     let api = null;
     // Before it is ready, any part that stops (or crashes in a watch mode) is a failed start.
-    const failed = () => app.children.filter(child => child.exitCode !== null || child.signalCode !== null || child.crashed);
+    // A traceback before the app answers is a failed start once nothing answers for 5 s.
+    const failed = () => app.children.filter(child => child.exitCode !== null || child.signalCode !== null || child.crashed
+      || (child.tracebackAt && Date.now() - child.tracebackAt > 5000));
     while (!found && Date.now() < deadline) {
       await wait(500);
       recording.poll();
@@ -408,7 +605,7 @@ async function main() {
       else if (answer) api ??= { ...answer, at: Date.now() };
       // An API without pages is accepted when nothing else serves pages for a while.
       // Right away only for a known API stack; otherwise pages may still come (Vite after the API…).
-      if (!found && api && (Date.now() - api.at > 20_000 || (parts.length === 1 && /^(Express|Fastify|Koa|Hono|NestJS)$/.test(parts[0].stack ?? '')))) found = api;
+      if (!found && api && (Date.now() - api.at > 20_000 || (parts.length === 1 && /^(Express|Fastify|Koa|Hono|NestJS|FastAPI)$/.test(parts[0].stack ?? '')))) found = api;
       if (found) {
         // The other parts may still be failing (a port taken…): a moment to see it.
         await wait(2000);
@@ -452,9 +649,14 @@ async function main() {
       busyTried.add(busy);
       const who = holder(busy);
       const port = await freePort();
-      extraEnv.PORT = String(port);
       predicted.add(port);
-      say(`! A porta ${busy} já está ocupada${who ? ` por outro programa (${who})` : ''}. Vou arrancar a app na porta ${port} (variável PORT).`);
+      if (parts[0].language === 'python') {
+        parts[0] = moveTo(parts[0], port);
+        say(`! A porta ${busy} já está ocupada ${portTakenBy(busy, who)}. Vou arrancar a app na porta ${port}.`);
+      } else {
+        extraEnv.PORT = String(port);
+        say(`! A porta ${busy} já está ocupada${who ? ` por outro programa (${who})` : ''}. Vou arrancar a app na porta ${port} (variável PORT).`);
+      }
       run = recordingName(project.name) + (minimal ? '-minimo' : '');
       continue;
     }
@@ -491,13 +693,29 @@ async function main() {
   const appUrl = found.url ?? `http://localhost:${found.port}/`;
   say('');
   say(`✓ App pronta em ${appUrl} (${seconds()})${minimal ? ' · modo mínimo' : ''}`);
-  if (found.status >= 500) say(`! A página inicial respondeu com erro ${found.status}. Veja as mensagens da app acima (faltam variáveis de ambiente?). O dossiê desse pedido mostra onde falhou.`);
+  // The capture may have chosen the minimal mode by itself (Python below the minimum…).
+  // (Unless it was announced before starting: a Python below the minimum.)
+  if (!minimal && !parts.some(part => part.python?.version && versionBelow(part.python.version))) {
+    const own = app.summary.starts.find(start => start.level === 'minimo');
+    if (own) say(`! Modo mínimo: ${own.reason}. Os dossiers mostram pedidos, fronteiras e browser, sem as funções do projeto.`);
+  }
+  if (found.status >= 500) say(`! A página inicial respondeu com erro ${found.status}. Veja as mensagens da app acima (faltam variáveis de ambiente?). O dossier desse pedido mostra onde falhou.`);
   if (found.page) {
     say('  Abra-a no browser e use-a: a barra do CodeTAC aparece no canto inferior direito.');
-    say('  Cada ação (clique, formulário…) fica com um dossiê; a barra abre-o.');
+    say('  Cada ação (clique, formulário…) fica com um dossier; a barra abre-o.');
     if (!options.noOpen && interactive) openBrowser(appUrl);
+  } else if (found.status === 404 && parts.some(part => /Vite|Next|Nuxt|Astro|Svelte|Remix|React|Angular/.test(part.stack ?? ''))) {
+    // A frontend that answers 404 on its home page is not an API: it did not find its page.
+    say(`! A página inicial respondeu 404. O frontend não encontrou a página (falta o index.html, ou a raiz no vite.config aponta para outra pasta?).`);
+    say('  O dossier desse pedido mostra-o. Os pedidos à API continuam a ser gravados.');
+  } else if (parts.length === 1 && parts[0].stack === 'FastAPI') {
+    // The interactive documentation is a page: the bar appears there, and each «Try it out» is an action.
+    const docs = `${appUrl}docs`;
+    say('  Esta app é uma API. Cada pedido fica com um dossier no painel.');
+    say(`  Para a experimentar no browser, com a barra do CodeTAC: ${docs} («Try it out» em cada rota).`);
+    if (!options.noOpen && interactive) openBrowser(docs);
   } else {
-    say('  Esta app responde sem páginas HTML (uma API). Faça pedidos como de costume; cada pedido fica com um dossiê no painel.');
+    say('  Esta app responde sem páginas HTML (uma API). Faça pedidos como de costume; cada pedido fica com um dossier no painel.');
   }
   say(`  Painel: ${panelUrl}  ·  Terminar: Ctrl+C`);
   say('');
@@ -511,23 +729,23 @@ async function main() {
       if (seenActions.has(id)) continue;
       seenActions.add(id);
       const link = `${panelUrl}/?action=${encodeURIComponent(id)}`;
-      if (!firstShown) { firstShown = true; say(`✓ Primeiro dossiê (${seconds()} desde o comando): ${link}`); }
+      if (!firstShown) { firstShown = true; say(`✓ Primeiro dossier (${seconds()} desde o comando): ${link}`); }
       else say(`• Ação gravada: ${link}`);
     }
     // A page that loads but where nothing is clicked yet (or that fails to
     // render): the dossier of its own load.
     if (!firstShown && summary.firstPage && Date.now() - summary.firstPage.seenAt > 8000) {
       firstShown = true;
-      say(`✓ Primeiro dossiê (${seconds()} desde o comando), o do carregamento da página: ${panelUrl}/?request=${encodeURIComponent(summary.firstPage.requestId)}`);
-      say('  Cada clique na app terá o seu próprio dossiê.');
+      say(`✓ Primeiro dossier (${seconds()} desde o comando), o do carregamento da página: ${panelUrl}/?request=${encodeURIComponent(summary.firstPage.requestId)}`);
+      say('  Cada clique na app terá o seu próprio dossier.');
     }
     if (!firstShown && summary.firstRequest && !found.page) {
       firstShown = true;
-      say(`✓ Primeiro dossiê (${seconds()} desde o comando): ${panelUrl}/?request=${encodeURIComponent(summary.firstRequest.requestId)}`);
+      say(`✓ Primeiro dossier (${seconds()} desde o comando): ${panelUrl}/?request=${encodeURIComponent(summary.firstRequest.requestId)}`);
     }
     if (!silentWarned && !minimal && summary.requests >= 3 && !summary.withFunctions.size && summary.functions === 0) {
       silentWarned = true;
-      say('! Já chegaram pedidos, mas nenhuma função do projeto foi observada. Os dossiês mostram pedidos e fronteiras.');
+      say('! Já chegaram pedidos, mas nenhuma função do projeto foi observada. Os dossiers mostram pedidos e fronteiras.');
       say('  «codetac diagnostico» explica porquê.');
     }
     // A part that fails later with a taken port: its requests could reach the