codetac 0.1.0 → 0.2.0

package/src/detect-python.mjs

@@ -0,0 +1,286 @@
+// Deteção de projetos Python (Etapa 12 Python, especificação 3.10): sinais,
+// interpretador, arranque e porta. Usado pelo detect.mjs; o caminho Node não
+// muda. Uma parte Python tem os mesmos campos que uma parte Node, mais
+// `language: 'python'` e `python` (interpretador, versão, módulos).
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const MINIMUM = [3, 12];
+const PROBE = fileURLToPath(new URL('./python/probe.py', import.meta.url));
+const SIGNALS = ['pyproject.toml', 'uv.lock', 'poetry.lock', 'Pipfile', 'Procfile', 'setup.py'];
+const ENVIRONMENTS = ['.venv', 'venv', 'env', '.env'];
+const SKIP = new Set(['node_modules', '__pycache__', 'site-packages', 'tests', 'test', 'migrations', 'alembic', 'docs', 'dist', 'build',
+  'scripts', 'static', 'templates', 'venv', 'env']);
+const PREFERRED = ['main.py', 'app.py', 'server.py', 'api.py', 'application.py', 'wsgi.py', 'asgi.py', '__init__.py'];
+const DEFAULT_PORT = { FastAPI: 8000, Flask: 5000 };
+// Tools a declared command may start with; they run as `python -m <tool>` with the project's interpreter.
+const MODULE_TOOLS = new Set(['uvicorn', 'flask', 'fastapi', 'gunicorn', 'hypercorn']);
+const RUNNERS = /^(?:uv run|poetry run|pipenv run|pdm run|rye run)\s+/;
+const SERVER_OF = { uvicorn: 'uvicorn', fastapi: 'uvicorn', flask: 'werkzeug', gunicorn: 'gunicorn', hypercorn: 'hypercorn', granian: 'granian', waitress: 'waitress' };
+
+function readText(path, limit = 200_000) {
+  try { return readFileSync(path, 'utf8').slice(0, limit); } catch { return ''; }
+}
+const isDirectory = path => { try { return statSync(path).isDirectory(); } catch { return false; } };
+const binary = (environment, name) => process.platform === 'win32' ? join(environment, 'Scripts', `${name}.exe`) : join(environment, 'bin', name);
+
+export function versionBelow(version, minimum = MINIMUM) {
+  const [major, minor] = String(version).split('.').map(Number);
+  return major < minimum[0] || (major === minimum[0] && minor < minimum[1]);
+}
+
+// A folder is a Python project with its own files (not only a virtual environment).
+export function hasPythonSignals(folder) {
+  if (SIGNALS.some(name => existsSync(join(folder, name)))) return true;
+  try {
+    const names = readdirSync(folder);
+    if (names.some(name => /^requirements.*\.txt$/.test(name))) return true;
+    return ENVIRONMENTS.some(name => existsSync(join(folder, name, 'pyvenv.cfg'))) && names.some(name => name.endsWith('.py'));
+  } catch { return false; }
+}
+
+// The project's own environment: a virtual environment in the folder, or the
+// one poetry or pipenv keeps elsewhere (only when the tool is installed).
+export function findEnvironment(folder) {
+  for (const name of ENVIRONMENTS) {
+    const environment = join(folder, name);
+    if (existsSync(join(environment, 'pyvenv.cfg')) && existsSync(binary(environment, 'python'))) {
+      return { path: environment, interpreter: binary(environment, 'python'), source: name };
+    }
+  }
+  const external = [['poetry.lock', 'poetry', ['env', 'info', '--path']], ['Pipfile', 'pipenv', ['--venv']]];
+  for (const [file, tool, args] of external) {
+    if (!existsSync(join(folder, file))) continue;
+    const result = spawnSync(tool, args, { cwd: folder, encoding: 'utf8', timeout: 15_000 });
+    const path = result.status === 0 ? result.stdout.trim().split('\n').pop() : '';
+    if (path && existsSync(binary(path, 'python'))) return { path, interpreter: binary(path, 'python'), source: tool };
+  }
+  return null;
+}
+
+// What the interpreter has: version, modules, missing dependencies (src/python/probe.py).
+export function probe(interpreter, folder) {
+  const result = spawnSync(interpreter, [PROBE, folder], { cwd: folder, encoding: 'utf8', timeout: 20_000,
+    env: { ...process.env, PYTHONPATH: '', PYTHONDONTWRITEBYTECODE: '1' } });
+  try { return JSON.parse(result.stdout.trim().split('\n').pop()); } catch { return null; }
+}
+
+// The application object: FastAPI(...) or Flask(...) assigned at module level.
+export function findApp(folder) {
+  const found = [];
+  const visit = (directory, depth) => {
+    let names = [];
+    try { names = readdirSync(directory).sort((a, b) => (PREFERRED.indexOf(a) + 1 || 99) - (PREFERRED.indexOf(b) + 1 || 99)); } catch { return; }
+    for (const name of names) {
+      if (name.startsWith('.') || SKIP.has(name)) continue;
+      const path = join(directory, name);
+      if (name.endsWith('.py')) {
+        const text = readText(path);
+        const assigned = text.match(/^(\w+)\s*(?::[^=\n]+)?=\s*(FastAPI|Flask)\(/m);
+        const factory = !assigned && /\bFlask\(/.test(text) && text.match(/^def (create_app|make_app)\(/m);
+        if (assigned || factory) {
+          const file = relative(folder, path);
+          const module = file.replace(/\.py$/, '').replace(/[\\/]__init__$/, '').split(sep).join('.');
+          found.push({ file, module, variable: assigned ? assigned[1] : `${factory[1]}()`, framework: assigned ? assigned[2] : 'Flask', depth,
+            main: /^if __name__ == ['"]__main__['"]/m.test(text), text });
+        }
+      } else if (depth < 2 && isDirectory(path) && !existsSync(join(path, 'pyvenv.cfg'))) visit(path, depth + 1);
+    }
+  };
+  visit(folder, 0);
+  found.sort((a, b) => a.depth - b.depth);
+  return found[0] ?? null;
+}
+
+// Commands the project declares: Procfile, task runners in pyproject.toml,
+// Makefile and README. Only those that start a Python server in development.
+const SERVER_COMMAND = /^(?:(?:uv run|poetry run|pipenv run|pdm run|rye run)\s+)?(?:uvicorn\s+\S+:\S+|fastapi\s+(?:dev|run)\b|flask\b.*\brun\b|gunicorn\s|hypercorn\s|granian\s|python3?\s+(?:-\S+\s+)*[\w./-]+\.py\b|python3?\s+-m\s+(?:uvicorn|flask|fastapi|gunicorn|hypercorn))/;
+const SERVES = /\b(?:app|application|server|api)\.run\(|\buvicorn\.run\(|\bserve\(|\bmake_server\(|\bsocketio\.run\(|\brun_simple\(/;
+export function declaredCommands(folder) {
+  const found = [];
+  const add = (command, source) => {
+    const clean = command.trim().replace(/^\$\s+/, '').replace(/\s+#.*$/, '');
+    if (SERVER_COMMAND.test(clean) && !found.some(item => item.command === clean)) found.push({ command: clean, source });
+  };
+  const procfile = readText(join(folder, 'Procfile')).match(/^web:\s*(.+)$/m);
+  if (procfile) add(procfile[1], 'Procfile');
+  const pyproject = readText(join(folder, 'pyproject.toml'));
+  for (const section of pyproject.split(/^\[/m).filter(part => /^tool\.(taskipy\.tasks|poe\.tasks|pdm\.scripts)\]/.test(part))) {
+    for (const match of section.matchAll(/^(dev|start|run|serve|server)\s*=\s*(?:\{[^}]*?cmd\s*=\s*)?["'](.+?)["']/gm)) add(match[2], `pyproject.toml (${match[1]})`);
+  }
+  const makefile = readText(join(folder, 'Makefile'));
+  for (const match of makefile.matchAll(/^(dev|run|start|serve|server):[^\n]*\n((?:\t[^\n]*\n?)+)/gm)) {
+    for (const line of match[2].split('\n')) add(line.replace(/^\t@?/, ''), `Makefile (${match[1]})`);
+  }
+  // README: only commands for development (reload, dev, debug, flask run, python file.py).
+  const readme = ['README.md', 'readme.md', 'README.rst', 'README'].map(name => readText(join(folder, name))).find(Boolean) ?? '';
+  for (const line of readme.split('\n')) {
+    const clean = line.trim().replace(/^\$\s+/, '').replace(/^`|`$/g, '');
+    if (/--reload|\bdev\b|--debug|flask\b.*\brun\b|^python3?\s+[\w./-]+\.py/.test(clean)) add(clean, 'README');
+  }
+  // A command that points at a file or module missing here belongs to another folder;
+  // `python file.py` counts only when that file starts a server (not a data script).
+  return found.filter(({ command }) => {
+    const script = command.match(/python3?\s+(?:-\S+\s+)*([\w./-]+\.py)\b/)?.[1];
+    if (script) return existsSync(join(folder, script)) && SERVES.test(readText(join(folder, script)));
+    const file = command.match(/fastapi\s+(?:dev|run)\s+([\w./-]+\.py)/)?.[1];
+    if (file) return existsSync(join(folder, file));
+    const target = command.match(/(?:uvicorn|gunicorn|hypercorn|granian)\s+(?:.*?\s)?([\w.]+):\w+/)?.[1];
+    if (target) return existsSync(join(folder, ...target.split('.')) + '.py') || existsSync(join(folder, ...target.split('.'), '__init__.py'));
+    return true;
+  });
+}
+
+function portFromCommand(command) {
+  const match = command.match(/(?:--port[= ]|-p[= ]?)(\d{2,5})\b/) ?? command.match(/(?:--bind|-b)[= ]\S*:(\d{2,5})\b/)
+    ?? command.match(/\$\{PORT:-(\d{2,5})\}/);
+  return match ? Number(match[1]) : null;
+}
+
+export function pythonPort(folder, { command = '', app = null, framework = null } = {}) {
+  const fromCommand = portFromCommand(command);
+  if (fromCommand) return { value: fromCommand, source: 'comando' };
+  for (const name of ['.env.local', '.env.development', '.env', '.flaskenv']) {
+    if (isDirectory(join(folder, name))) continue;
+    const match = readText(join(folder, name)).match(/^\s*(?:export\s+)?(?:FLASK_RUN_|APP_|UVICORN_)?PORT\s*=\s*["']?(\d{2,5})/m);
+    if (match) return { value: Number(match[1]), source: name };
+  }
+  // python app.py: the port the file itself passes (app.run(port=…), uvicorn.run(…, port=…)).
+  if (app && /python/.test(command)) {
+    const match = app.text.match(/\bport\s*=\s*(?:int\(\s*os\.(?:environ\.get|getenv)\(\s*["']PORT["']\s*,\s*["']?)?(\d{2,5})/);
+    if (match) return { value: Number(match[1]), source: app.file };
+  }
+  const name = framework ?? app?.framework;
+  if (/fastapi dev|uvicorn/.test(command) || name === 'FastAPI') return { value: 8000, source: 'omissão do uvicorn' };
+  if (/flask/.test(command) || name === 'Flask') return { value: 5000, source: 'omissão do Flask' };
+  return null;
+}
+
+// The command as argv, with the project's interpreter and the port.
+export function commandFor(part, port) {
+  const interpreter = part.python.interpreter ?? 'python3';
+  if (part.python.declared) {
+    let text = part.python.declared.replace(RUNNERS, '');
+    text = text.replace(/\$\{PORT(?::-\d+)?\}|\$PORT\b/g, String(port));
+    if (portFromCommand(text) && !/\$\{PORT/.test(part.python.declared)) {
+      text = text.replace(/(--port[= ]|-p[= ]?)\d{2,5}\b/, `$1${port}`).replace(/((?:--bind|-b)[= ]\S*:)\d{2,5}\b/, `$1${port}`);
+    }
+    const [first, ...rest] = text.split(/\s+/).filter(Boolean);
+    // A known server without a port option gets one: the port must be ours to choose.
+    const tool = first === 'python' || first === 'python3' ? (rest[0] === '-m' ? rest[1] : null) : first;
+    if (!portFromCommand(text) && !/\$\{?PORT/.test(part.python.declared)) {
+      if (tool === 'uvicorn' || tool === 'hypercorn' || (tool === 'fastapi' && /\b(dev|run)\b/.test(text)) || (tool === 'flask' && /\brun\b/.test(text))) rest.push('--port', String(port));
+      else if (tool === 'gunicorn') rest.push('--bind', `127.0.0.1:${port}`);
+    }
+    if (/^python3?$/.test(first)) return [interpreter, ...rest];
+    if (MODULE_TOOLS.has(first)) return [interpreter, '-m', first, ...rest];
+    return [first, ...rest];
+  }
+  const { app } = part.python;
+  switch (part.python.how) {
+    case 'fastapi dev': return [interpreter, '-m', 'fastapi', 'dev', app.file, '--port', String(port)];
+    case 'uvicorn': return [interpreter, '-m', 'uvicorn', `${app.module}:${app.variable}`, '--reload', '--port', String(port)];
+    case 'flask': return [interpreter, '-m', 'flask', '--app', app.variable.endsWith('()') ? `${app.module}:${app.variable}` : app.module, 'run', '--debug', '--port', String(port)];
+    case 'python': return [interpreter, app.file];
+    default: return null;
+  }
+}
+
+// Things to say before starting (limits of the capture for this command).
+function notesFor(command, python) {
+  const notes = [];
+  const text = command.join(' ');
+  if (python.version && versionBelow(python.version)) {
+    notes.push(`O Python do projeto é o ${python.version}: a app corre em modo mínimo (pedidos, fronteiras e browser, sem seguir as funções). Para as ver, use o Python ${MINIMUM.join('.')} ou mais recente no ambiente do projeto.`);
+  }
+  const flags = text.match(/python3?(?:\.\d+)?\s+((?:-[a-zA-Z]+\s+)+)/)?.[1] ?? '';
+  const ignored = flags.split(/\s+/).filter(flag => /^-[a-zA-Z]*[EIS]/.test(flag));
+  if (ignored.length) notes.push(`O comando usa ${ignored.join(' ')}: com essa opção o Python ignora o PYTHONPATH ou o site, e a app corre sem ser observada. Retire-a para usar o CodeTAC.`);
+  if (/\bgranian\b/.test(text)) notes.push('O granian chama a app a partir de Rust e o CodeTAC ainda não o reconhece: a app corre, mas os pedidos não ficam com dossier. Com o uvicorn, fica tudo visível.');
+  if (/\bhypercorn\b/.test(text)) notes.push('O hypercorn ainda não é reconhecido: a app corre, mas os pedidos não ficam com dossier. Com o uvicorn, fica tudo visível.');
+  return notes;
+}
+
+// One folder with a Python project: how to start it.
+export function describePythonFolder(folder, top = folder) {
+  if (!hasPythonSignals(folder)) return null;
+  const environment = findEnvironment(folder);
+  const probed = environment ? probe(environment.interpreter, folder) : null;
+  const modules = new Set(probed?.modules ?? []);
+  const app = findApp(folder);
+  const declared = declaredCommands(folder)[0] ?? null;
+  const django = existsSync(join(folder, 'manage.py'));
+  let how = null;
+  if (declared) how = 'declared';
+  else if (app?.framework === 'FastAPI') {
+    // Without an environment, the command is the one it will have once created.
+    if (!probed || (modules.has('fastapi_cli') && modules.has('fastapi.__main__'))) how = 'fastapi dev';
+    else if (modules.has('uvicorn')) how = 'uvicorn';
+    else if (app.main) how = 'python';
+    else how = 'uvicorn';
+  } else if (app?.framework === 'Flask') how = modules.has('flask') || !probed ? 'flask' : app.main ? 'python' : 'flask';
+  const python = { interpreter: environment?.interpreter ?? null, environment: environment?.path ?? null, source: environment?.source ?? null,
+    version: probed?.version ?? null, modules: [...modules], missing: probed?.missing ?? [], app, how, declared: declared?.command ?? null,
+    declaredSource: declared?.source ?? null, django };
+  const framework = app?.framework ?? (/fastapi|uvicorn/.test(declared?.command ?? '') ? 'FastAPI' : /flask/.test(declared?.command ?? '') ? 'Flask' : null);
+  const port = how ? pythonPort(folder, { command: declared?.command ?? (how === 'python' ? 'python' : how), app, framework }) : null;
+  const part = {
+    folder, part: relative(top, folder) || '.', name: basename(folder), language: 'python', manager: existsSync(join(folder, 'uv.lock')) ? 'uv'
+      : existsSync(join(folder, 'poetry.lock')) ? 'poetry' : existsSync(join(folder, 'Pipfile')) ? 'pipenv' : 'pip',
+    stack: framework, script: declared ? { name: declared.source, command: declared.command } : null, entry: null,
+    command: null, foreign: null, port, installed: Boolean(probed) && !python.missing.length, workspaces: false, python,
+  };
+  if (how) part.command = commandFor(part, port?.value ?? DEFAULT_PORT[framework] ?? 8000);
+  // python app.py: the server is the one the file starts, known only when it runs.
+  part.server = SERVER_OF[part.command?.find(token => SERVER_OF[token]) ?? ''] ?? null;
+  part.notes = part.command ? notesFor(part.command, python) : [];
+  // The configuration the app may need (cp .env.example .env): the user's to make.
+  if (part.command && !existsSync(join(folder, '.env')) && ['.env.example', '.env.sample', '.env.template'].some(name => existsSync(join(folder, name)))) {
+    part.notes.push('O projeto tem um .env.example, mas não um .env. Se a app precisar da configuração, copie-o (cp .env.example .env) e preencha-o.');
+  }
+  return part;
+}
+
+// The same part on another port (a taken port, or one the others must follow).
+export function moveTo(part, port) {
+  const command = commandFor(part, port);
+  const moved = { ...part, port: { value: port, source: 'escolhida pelo CodeTAC' }, command: command ?? part.command };
+  // python app.py, or a declared command without a port option: the PORT variable.
+  if (!command || !command.join(' ').includes(String(port))) moved.env = { ...part.env, PORT: String(port) };
+  return moved;
+}
+
+// The environment of a Python part: its virtual environment first in PATH.
+export function environmentOf(part) {
+  const env = { ...part.env };
+  if (part.python?.environment && part.python.source !== 'poetry' && part.python.source !== 'pipenv') env.VIRTUAL_ENV = part.python.environment;
+  if (part.python?.environment) env.PATH = [join(part.python.environment, process.platform === 'win32' ? 'Scripts' : 'bin'), process.env.PATH].join(process.platform === 'win32' ? ';' : ':');
+  return env;
+}
+
+// Interpreters on this computer, newest first (for a new environment).
+export function interpreters() {
+  const names = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3', 'python'];
+  const found = [];
+  for (const name of names) {
+    const result = spawnSync(name, ['-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3]); print(sys.executable)'], { encoding: 'utf8', timeout: 10_000 });
+    if (result.status !== 0) continue;
+    const [version, executable] = result.stdout.trim().split('\n');
+    if (!found.some(item => item.executable === executable)) found.push({ name, version, executable });
+  }
+  const key = version => version.split('.').map(Number).reduce((total, part) => total * 1000 + part, 0);
+  return found.sort((a, b) => key(b.version) - key(a.version));
+}
+
+// The Vite proxy of a frontend: which ports it sends to, and the variable that sets each one.
+export function proxyOf(folder, script = '') {
+  // The configuration named in the script (vite --config ./config/vite.config.ts), else the usual names.
+  const named = String(script).match(/--config[= ](\S+)/)?.[1];
+  const text = [...(named ? [named] : []), 'vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.mts'].map(name => readText(join(folder, name))).find(Boolean) ?? '';
+  if (!/\bproxy\b/.test(text)) return null;
+  const variables = [...text.matchAll(/process\.env\.(\w+)\s*(?:\?\?|\|\|)\s*['"]?(\d{2,5})/g)].map(match => ({ variable: match[1], port: Number(match[2]) }));
+  const literal = [...text.matchAll(/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]):(\d{2,5})\b/g)].map(match => Number(match[1]));
+  return { variables, literal };
+}

package/src/detect.mjs

@@ -3,6 +3,7 @@
 // fica em `missing`, para o comando perguntar ao utilizador.
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { basename, join, relative } from 'node:path';
+import { describePythonFolder, hasPythonSignals } from './detect-python.mjs';
 
 // Ordem de preferência dos scripts de desenvolvimento.
 const SCRIPTS = ['dev', 'start:dev', 'develop', 'serve', 'dev:server', 'server', 'start'];
@@ -26,7 +27,8 @@ const STACKS = [
 ];
 const ENTRIES = ['server.js', 'server.mjs', 'server.ts', 'index.js', 'index.mjs', 'index.ts', 'app.js', 'app.ts',
   'src/server.ts', 'src/server.js', 'src/index.ts', 'src/index.js', 'src/main.ts', 'src/app.ts', 'server/index.ts', 'server/index.js'];
-const SKIP_FOLDERS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', 'public', 'docs', 'test', 'tests', 'e2e', 'scripts']);
+const SKIP_FOLDERS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', 'public', 'docs', 'test', 'tests', 'e2e', 'scripts',
+  'venv', 'env', '__pycache__', 'site-packages']);
 
 function readJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
@@ -138,7 +140,8 @@ function childFolders(root) {
       if (name.startsWith('.') || SKIP_FOLDERS.has(name)) continue;
       const path = join(folder, name);
       try { if (!statSync(path).isDirectory()) continue; } catch { continue; }
-      if (existsSync(join(path, 'package.json'))) found.push(path);
+      // A folder with its own package.json, or a Python project (api/, backend/…).
+      if (existsSync(join(path, 'package.json')) || hasPythonSignals(path)) found.push(path);
       else if (depth < 1) visit(path, depth + 1);
       if (depth < 1 && ['apps', 'packages'].includes(name)) visit(path, depth + 1);
     }
@@ -175,15 +178,23 @@ function plainEntry(root) {
 // package.json whose script already starts everything is enough on its own;
 // otherwise the parts with their own scripts are offered (client + server…).
 export function detectProject(root) {
-  const top = describeFolder(root) ?? plainEntry(root);
-  const parts = childFolders(root).map(folder => describeFolder(folder, root)).filter(part => part?.command);
+  const node = describeFolder(root);
+  // A package.json that starts nothing (only tooling) does not hide a Python app in the same folder.
+  const top = (node?.command ? node : null) ?? describePythonFolder(root) ?? node ?? plainEntry(root);
+  const parts = childFolders(root).map(folder => describeFolder(folder, root) ?? describePythonFolder(folder, root)).filter(part => part?.command);
   let start = [];
   // Without a "dev" script, several "dev:*" scripts (dev:server + dev:client…)
   // are started together: that is how such projects run in development.
   const pieces = top ? devPieces(top) : [];
   if (pieces.length > 1) start = pieces;
-  else if (top?.command) start = [top];
+  // A frontend at the top and a Python API in a subfolder (backend/, api/): both run,
+  // unless the top script already starts Python itself.
+  else if (top?.command && top.language !== 'python' && !/^(python3?|uvicorn)$/.test(top.foreign ?? '') && parts.some(part => part.language === 'python')) {
+    start = [top, ...parts.filter(part => part.language === 'python')];
+  } else if (top?.command) start = [top];
   else if (parts.length === 1) start = parts;
+  // A frontend and a Python API (web/ + api/): both run in development.
+  else if (!top?.command && parts.some(part => part.language === 'python') && parts.some(part => part.language !== 'python')) start = parts;
   const missing = [];
   if (!top && !parts.length) missing.push('package');
   else if (!start.length && parts.length > 1) missing.push('part');
@@ -193,6 +204,10 @@ export function detectProject(root) {
 
 // The sentence the command shows before starting.
 export function describeStart(part) {
-  const what = part.script ? `${part.command.join(' ')}  (script «${part.script.name}»: ${part.script.command})` : part.command.join(' ');
+  const shown = part.language === 'python' && part.python.interpreter
+    ? part.command.map(token => token === part.python.interpreter ? relative(part.folder, token) || token : token) : part.command;
+  const what = part.language === 'python'
+    ? `${shown.join(' ')}${part.python.declared ? `  (de ${part.python.declaredSource})` : ''}${part.python.version ? `  · Python ${part.python.version}` : ''}`
+    : part.script ? `${part.command.join(' ')}  (script «${part.script.name}»: ${part.script.command})` : part.command.join(' ');
   return `${part.part === '.' ? '' : `[${part.part}] `}${part.stack ? `${part.stack} · ` : ''}${what}`;
 }

package/src/diagnose.mjs

@@ -5,6 +5,7 @@ import http from 'node:http';
 import { join, relative } from 'node:path';
 import { dataDirectory } from './home.mjs';
 import { detectProject, describeStart } from './detect.mjs';
+import { MINIMUM, versionBelow } from './detect-python.mjs';
 import { recordingsOf, summarize } from './recording.mjs';
 import { describeConfig, loadConfig } from './ai.mjs';
 
@@ -18,6 +19,7 @@ const REASONS = {
   'generator-skipped': 'generators (correm, mas não aparecem)',
   'parameter-redeclaration-skipped': 'funções que redeclaram um parâmetro (correm, mas não aparecem)',
   'direct-eval-skipped': 'funções com eval direto (correm, mas não aparecem)',
+  'template-lines-unmapped': 'templates sem ligação às linhas do ficheiro (aparecem como um só passo)',
 };
 
 function ping(port) {
@@ -41,6 +43,23 @@ function panelConfig(port) {
   });
 }
 
+// A Python part: interpreter, version, dependencies, server and start (Etapa 12 Python).
+function pythonPart(part, { ok, bad, note }) {
+  const label = part.part === '.' ? '' : `[${part.part}] `;
+  const { python } = part;
+  if (!python.interpreter) bad(`${label}Sem ambiente Python (.venv).`, 'codetac cria-o e instala as dependências (pergunta antes; --sim responde que sim).');
+  else if (!python.version) bad(`${label}O Python do ambiente (${relative(part.folder, python.interpreter)}) não respondeu.`, 'O ambiente pode estar partido: apague o .venv e volte a correr codetac.');
+  else if (versionBelow(python.version)) note(`${label}Python ${python.version} (${relative(part.folder, python.interpreter)}): só modo mínimo (pedidos, fronteiras e browser, sem as funções).`,
+    `Crie o ambiente com o Python ${MINIMUM.join('.')} ou mais recente.`);
+  else ok(`${label}Python ${python.version} (${relative(part.folder, python.interpreter) || python.interpreter}): consegue seguir as funções do projeto.`);
+  if (python.interpreter && python.missing.length) bad(`${label}Faltam dependências: ${python.missing.slice(0, 8).join(', ')}${python.missing.length > 8 ? '…' : ''}.`, 'codetac instala-as (pergunta antes).');
+  ok(`Arranque: ${describeStart(part)}`);
+  if (part.server) ok(`${label}Servidor: ${part.server}.`);
+  if (part.port) ok(`${label}Porta provável: ${part.port.value} (${part.port.source}). Se estiver ocupada, o comando escolhe outra.`);
+  // The version note is already the first line.
+  for (const text of (part.notes ?? []).filter(text => !text.startsWith('O Python do projeto'))) note(`${label}${text}`);
+}
+
 export async function diagnose(root, { panelPort = 4000, out = text => process.stdout.write(`${text}\n`) } = {}) {
   let problems = 0;
   const ok = text => out(`  ✓ ${text}`);
@@ -58,8 +77,12 @@ export async function diagnose(root, { panelPort = 4000, out = text => process.s
   const project = detectProject(root);
   if (project.missing.includes('package')) bad('Não há package.json nem ficheiro de servidor (server.js, index.js…) nesta pasta.', 'Corra o comando na pasta da app, ou indique o arranque: codetac . -- node server.js');
   else if (project.missing.includes('part')) note(`Tem várias partes: ${project.parts.map(part => part.part).join(', ')}. O comando pergunta quais arrancar.`);
-  else if (project.missing.includes('command')) bad('O package.json não tem um script de arranque (dev, start…).', 'Indique o comando: codetac . -- <comando>');
+  else if (project.missing.includes('command') && project.top?.language === 'python') {
+    if (project.top.python.django) bad('Projeto Django: o CodeTAC ainda não o suporta (só FastAPI e Flask).');
+    else bad('Projeto Python, mas não encontrei a app (FastAPI(...) ou Flask(...)) nem um comando no Procfile, Makefile ou README.', 'Indique o comando: codetac . -- uvicorn main:app --reload');
+  } else if (project.missing.includes('command')) bad('O package.json não tem um script de arranque (dev, start…).', 'Indique o comando: codetac . -- <comando>');
   for (const part of project.start.length ? project.start : project.parts) {
+    if (part.language === 'python') { pythonPart(part, { ok, bad, note }); continue; }
     ok(`Arranque: ${describeStart(part)}`);
     if (part.port) ok(`Porta provável: ${part.port.value} (${part.port.source}). A porta real é lida quando a app arranca.`);
     if (!part.installed) bad(`As dependências de ${part.part === '.' ? 'o projeto' : part.part} não estão instaladas.`, `${part.manager === 'bun' ? 'npm' : part.manager} install (ou codetac --sim, que instala)`);
@@ -85,16 +108,23 @@ export async function diagnose(root, { panelPort = 4000, out = text => process.s
     return problems ? 1 : 0;
   }
   const summary = summarize(last.folder);
-  ok(`${last.name} (${new Date(last.changed).toLocaleString('pt-PT')}), ${summary.processes.size} processo(s) Node observados.`);
+  // Processes by runtime; a supervisor (reloader) serves nothing and is left out.
+  const serving = summary.starts.filter(start => !summary.supervisors.has(start.process));
+  const pythons = [...new Set(serving.filter(start => start.python).map(start => start.python))];
+  const nodes = serving.filter(start => !start.python).length;
+  const runtimes = [nodes && `${nodes} Node`, pythons.length && `${serving.length - nodes} Python ${pythons.join(', ')}`].filter(Boolean).join(', ');
+  ok(`${last.name} (${new Date(last.changed).toLocaleString('pt-PT')}), ${serving.length} processo(s) observados${runtimes ? ` (${runtimes})` : ''}.`);
+  if (summary.supervisors.size) ok(`${summary.supervisors.size} processo(s) supervisor do reloader (só vigiam os ficheiros; não contam).`);
+  if (summary.servers.size) ok(`Servidor: ${[...summary.servers].join(', ')}.`);
   const minimal = summary.starts.find(start => start.level === 'minimo');
   if (minimal) note(`Modo mínimo: as funções do projeto não foram seguidas (${minimal.reason ?? 'sem motivo registado'}). Pedidos, fronteiras e browser sim.`,
     'Se a app arranca sem o CodeTAC mas não com ele, envie estas linhas e as mensagens do arranque.');
   if (summary.ports.size) ok(`Portas abertas pela app: ${[...summary.ports].join(', ')}.`);
-  else if (!summary.requests) bad('A captura não viu a app abrir nenhuma porta.', 'A app arrancou? Se o servidor não for Node (bun, deno…), não é observado.');
+  else if (!summary.requests) bad('A captura não viu a app abrir nenhuma porta.', 'A app arrancou? Se o servidor não for Node nem Python (bun, deno…), não é observado.');
   if (!minimal) {
     if (summary.files) ok(`Ficheiros do projeto preparados: ${summary.files} (${summary.functions} funções).`);
     else if (summary.requests) bad('Nenhum ficheiro do projeto passou pelo CodeTAC.',
-      'O servidor pode estar a correr código já empacotado sem source map, ou fora da pasta do projeto. Os dossiês mostram só pedidos e fronteiras.');
+      'O servidor pode estar a correr código já empacotado sem source map, ou fora da pasta do projeto. Os dossiers mostram só pedidos e fronteiras.');
     const failed = summary.failed.length;
     if (failed) {
       note(`${failed} ficheiro(s) correm sem ser seguidos (não foi possível prepará-los):`);
@@ -112,7 +142,7 @@ export async function diagnose(root, { panelPort = 4000, out = text => process.s
   } else note('Ainda não chegou nenhum pedido.', 'Abra a app no browser e use-a.');
   if (summary.pages) ok(`Páginas servidas com a barra do CodeTAC: ${summary.pages}.`);
   else if (summary.requests && !summary.actions.size) note('Nenhuma página HTML passou pelo servidor observado: a barra não foi injetada.',
-    'Se a página vem de outro servidor (outro processo, não Node), abra-a através do servidor Node da app.');
+    'Se a página vem de outro servidor (um processo que o CodeTAC não observa), abra-a através do servidor observado da app.');
   if (summary.actions.size) ok(`Ações do browser gravadas: ${summary.actions.size}.`);
   else if (summary.pages) note('A barra está na página, mas ainda não chegou nenhuma ação.', 'Clique em algo na app. Se nada aparecer, veja a consola do browser (erros de CSP?).');
 

package/src/digest.mjs

@@ -1,4 +1,4 @@
-// Vista agrupada do dossiê (Fase 3): árvore de passos com o ruído agrupado,
+// Vista agrupada do dossier (Fase 3): árvore de passos com o ruído agrupado,
 // uma frase de finalidade por função e por fronteira, e o resumo dos efeitos
 // permanentes. Tudo deriva dos factos gravados; nada é removido, só agrupado
 // (cada grupo guarda os passos originais para a expansão).
@@ -46,7 +46,7 @@ function generated(node, root) {
   return within.split('/').slice(0, -1).some(part => part.startsWith('.'));
 }
 function trivial(node) {
-  return node.type === 'function' && !node.children.length && !node.error && !node.detail && node.finished !== false
+  return node.type === 'function' && !node.opaque && !node.children.length && !node.error && !node.detail && node.finished !== false
     && (node.durationMs ?? 0) < TRIVIAL_MS && (node.endLine == null || node.endLine - node.line <= TRIVIAL_LINES);
 }
 const sum = (nodes, key = 'durationMs') => nodes.reduce((total, node) => total + (node[key] ?? 0), 0);
@@ -154,10 +154,16 @@ function blocks(nodes, ctx) {
 }
 
 // What a function did, from the boundaries in its subtree and the functions it called.
+// Code compiled from a template (Jinja, and any engine whose functions keep
+// the template's file): what it does is produce HTML.
+const TEMPLATE_FILE = /\.(html?|jinja2?|j2|njk|twig|hbs|ejs|mustache|liquid)$/i;
+
 function functionSentence(node, ctx) {
   const t = texts(ctx.lang);
   const facts = collect(node);
   const parts = [];
+  const template = TEMPLATE_FILE.test(node.file ?? '');
+  if (template && !node.opaque) parts.push(t.templatePart(node.file.split('/').pop()));
   const db = facts.boundaries.filter(item => item.kind === 'base-de-dados');
   const structure = db.filter(item => STRUCTURE.has(item.operation));
   if (structure.length) parts.push(t.dbSetupPart(structure.length));
@@ -187,7 +193,9 @@ function functionSentence(node, ctx) {
   const auth = [...new Set(kinds('autenticação').map(item => item.provider ?? item.library))];
   if (auth.length) parts.push(t.authPart(names(auth, t.and)));
   const callees = [...new Set(node.children.filter(item => item.type === 'function' && !generated(item, ctx.root)).map(item => item.function))];
-  if (!facts.boundaries.length) parts.push(t.noBoundary);
+  // An opaque step (compiled code, an unmapped template): only what it is.
+  if (node.opaque) parts.push(t.opaque);
+  else if (!facts.boundaries.length && !template) parts.push(t.noBoundary);
   if (callees.length) parts.push(t.calls(names(callees, t.and)));
   if (node.error) parts.push(t.error);
   else if (node.finished === false) parts.push(t.unfinished);
@@ -307,7 +315,13 @@ export function digestAction(dossier, { lang = 'pt-PT' } = {}) {
   const trigger = dossier.timeline.find(item => item.type === 'trigger')?.trigger;
   const a = t.action;
   const opening = !trigger ? a.continuation : trigger.event === 'submit' ? a.submit(dossier.label) : trigger.event === 'change' ? a.change(dossier.label) : a.click(dossier.label);
-  const requests = timeline.filter(item => item.type === 'request' && item.browser?.sameOrigin).map(item => a.request(item.browser.method, item.browser.path, item.browser.status));
+  // Requests of the page (fetch, XHR) and those of a full navigation (a form
+  // that loads the next page): the server parts of each new document.
+  // Requests to another origin (an API on another port without a proxy, an
+  // outside service) are requests too: named with their host.
+  const requests = timeline.flatMap(item => item.type === 'request' && item.browser ? [a.request(item.browser.method,
+      item.browser.sameOrigin || !item.browser.host ? item.browser.path : `${item.browser.host}${item.browser.path}`, item.browser.status)]
+    : item.type === 'document' ? (item.server ?? []).map(part => a.request(part.request.method, part.request.path, part.request.status)) : []);
   const navigations = timeline.filter(item => item.type === 'navigation' || item.type === 'document').map(item => a.navigates(item.path ?? item.page?.path));
   const screens = dossier.timeline.filter(item => item.type === 'screen');
   const changed = screens.some(item => { const s = item.screen ?? {}; return s.added || s.removed || s.text || s.attributes || s.title || s.stateChanged?.length; });

package/src/page.mjs

@@ -156,6 +156,22 @@ function withoutLength(headers) {
   return Object.fromEntries(Object.entries(headers).filter(([key]) => !DROP.has(key.toLowerCase())));
 }
 
+// Where the tag goes: after <head ...>; in a whole document without a head,
+// before <body>, or else after <html ...> or <!doctype html> (error pages such
+// as werkzeug's have neither head nor body). Fragments (partial HTML
+// responses) are left intact: -1. null while more of the body is needed.
+// The same rule is in src/python/codetac_py/page.py.
+export function tagPosition(view, final) {
+  const head = view.match(/<head(?:\s[^>]*)?>/i);
+  if (head) return head.index + head[0].length;
+  if (!final) return null;
+  const body = view.search(/<body[\s>]/i);
+  if (body >= 0) return body;
+  const opening = view.match(/^(?:\s|<!--[\s\S]*?-->)*(?:<!doctype html[^>]*>(?:\s|<!--[\s\S]*?-->)*)?<html(?:\s[^>]*)?>/i)
+    ?? view.match(/^(?:\s|<!--[\s\S]*?-->)*<!doctype html[^>]*>/i);
+  return opening ? opening[0].length : -1;
+}
+
 export function injectScript(request, response) {
   delete request.headers['accept-encoding'];
   let mode = null; // null: undecided; 'pass'; 'buffer'; 'done'
@@ -181,15 +197,11 @@ export function injectScript(request, response) {
   const decide = self => { if (mode === null && !self.headersSent) self.writeHead(self.statusCode); if (mode === null) mode = 'pass'; };
   const toBuffer = (chunk, encoding) => Buffer.isBuffer(chunk) ? chunk : chunk instanceof Uint8Array ? Buffer.from(chunk)
     : Buffer.from(String(chunk), typeof encoding === 'string' ? encoding : 'utf8');
-  // Inserts the tag after <head ...>, or before <body> when there is no head.
-  // Fragments (no head/body, as in partial HTML responses) are left intact.
   function take(final) {
     const all = Buffer.concat(chunks);
-    const view = all.toString('latin1');
-    const head = view.match(/<head(?:\s[^>]*)?>/i);
-    let at = head ? head.index + head[0].length : -1;
-    if (at < 0 && (final || all.length > MAX_BUFFER)) at = view.search(/<body[\s>]/i);
-    if (at < 0) return final || all.length > MAX_BUFFER ? all : null;
+    const at = tagPosition(all.toString('latin1'), final || all.length > MAX_BUFFER);
+    if (at === null) return null;
+    if (at < 0) return all;
     return Buffer.concat([all.subarray(0, at), Buffer.from(TAG), all.subarray(at)]);
   }