codetac 0.1.1 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codetac",
-  "version": "0.1.1",
-  "description": "codeTAC — perceber o que o código da sua app Node faz, ação a ação: do clique no browser às funções do servidor, base de dados e serviços externos.",
+  "version": "0.2.0",
+  "description": "codeTAC — perceber o que o código da sua app Node ou Python faz, ação a ação: do clique no browser às funções do servidor, base de dados e serviços externos.",
   "keywords": [
     "debug",
     "trace",
@@ -10,6 +10,9 @@
     "nextjs",
     "vite",
     "express",
+    "python",
+    "fastapi",
+    "flask",
     "ai-generated",
     "vibe-coding",
     "dossier"
@@ -29,7 +32,9 @@
     "codetac": "src/cli.mjs"
   },
   "files": [
-    "src/"
+    "src/",
+    "!**/__pycache__/",
+    "!**/*.pyc"
   ],
   "engines": {
     "node": ">=24.0.0"
@@ -37,10 +42,10 @@
   "scripts": {
     "test": "node --test test/*.test.mjs",
     "test:stacks": "node scripts/validate-stacks.mjs",
-    "check": "node --check src/register.mjs && node --check src/transform.mjs && node --check src/runtime.mjs && node --check src/boundaries.mjs && node --check src/store.mjs && node --check src/panel.mjs && node --check src/page.mjs && node --check src/origins.mjs && node --check src/action-view.mjs && node --check src/browser/bar.js && node --check src/digest.mjs && node --check src/sentences.mjs && node --check src/ai.mjs && node --check src/cli.mjs && node --check src/detect.mjs && node --check src/recording.mjs && node --check src/diagnose.mjs",
+    "check": "node --check src/register.mjs && node --check src/transform.mjs && node --check src/runtime.mjs && node --check src/boundaries.mjs && node --check src/store.mjs && node --check src/panel.mjs && node --check src/page.mjs && node --check src/origins.mjs && node --check src/action-view.mjs && node --check src/browser/bar.js && node --check src/digest.mjs && node --check src/sentences.mjs && node --check src/ai.mjs && node --check src/cli.mjs && node --check src/detect.mjs && node --check src/detect-python.mjs && node --check src/recording.mjs && node --check src/diagnose.mjs",
     "test:performance": "node scripts/benchmark-functions.mjs",
     "panel": "node src/panel.mjs",
-    "test:browser": "node scripts/accept-browser.mjs docs/aceitacao-browser-exemplo.json",
+    "test:browser": "node scripts/accept-browser.mjs scripts/ensaios/browser-exemplo.json",
     "codetac": "node src/cli.mjs"
   },
   "dependencies": {

package/readme.md

@@ -2,7 +2,7 @@
 
 **Perceber o que o código da sua app faz, ação a ação.**
 
-*See what your app's code does, one click at a time: a local tool for Node.js apps, including those generated by AI tools (Lovable, Bolt, v0, Cursor, Replit, Claude Code…). Explanations are in Portuguese by default (`CODETAC_LANG=en` for English).*
+*See what your app's code does, one click at a time: a local tool for Node.js and Python (FastAPI, Flask) apps, including those generated by AI tools (Lovable, Bolt, v0, Cursor, Replit, Claude Code…). Explanations are in Portuguese by default (`CODETAC_LANG=en` for English).*
 
 ![Dossier de um clique no botão «Sign in»: as funções do servidor que correram, com o ficheiro e a linha, e as leituras da base de dados](https://raw.githubusercontent.com/deltaxmodules/codetacvibe/main/.github/imagens/dossier.png)
 
@@ -24,9 +24,9 @@ Tudo corre no seu computador. O código da app não é alterado.
 
 ## Para que apps serve
 
-**Apps web em Node.js (JavaScript ou TypeScript), a correr no seu computador.** Incluindo as feitas com Lovable, Bolt, v0, Cursor, Replit ou Claude Code.
+**Apps web em Node.js (JavaScript ou TypeScript) ou em Python (FastAPI ou Flask), a correr no seu computador.** Incluindo as feitas com Lovable, Bolt, v0, Cursor, Replit ou Claude Code.
 
-**Ensaiado com:**
+**Node.js — ensaiado com:**
 - Next.js (incluindo a versão 16);
 - Vite + React;
 - Express;
@@ -35,11 +35,19 @@ Tudo corre no seu computador. O código da app não é alterado.
 
 Outras apps Node devem funcionar (Nuxt, SvelteKit, Astro, Remix, NestJS, Fastify…), mas ainda não foram ensaiadas. Se algo falhar, veja a [secção 6](#6-quando-algo-não-funciona).
 
+**Python — ensaiado com:**
+- FastAPI (funções `async def` e `def`), com o uvicorn, o `fastapi dev` ou o gunicorn;
+- Flask, com o `flask run`, o `app.run()`, o gunicorn ou o waitress, incluindo os templates Jinja;
+- um frontend Node (por exemplo Vite + React) com uma API Python na mesma pasta ou numa subpasta (`backend/`, `api/`…): arrancam juntos, e o dossier segue o clique do browser até às funções Python;
+- projetos gerados pelo Claude Code, Replit Agent, Lovable, Codex e Cursor.
+
+Para seguir as funções da app, precisa do **Python 3.12 ou mais recente**. Com o Python 3.8 a 3.11, o codeTAC funciona em **modo mínimo**: mostra os pedidos, as fronteiras e o browser, mas não as funções. Com o hypercorn ou o granian, a app corre, mas as ações não ficam com dossier (o comando avisa e sugere o uvicorn).
+
 **Mostra à parte quando a app usa:**
 
 | | |
 | --- | --- |
-| Base de dados | Postgres (`pg`), MySQL (`mysql2`), SQLite (`better-sqlite3`, `node:sqlite`), Supabase (com a tabela e a operação) |
+| Base de dados | Postgres (`pg`), MySQL (`mysql2`), SQLite (`better-sqlite3`, `node:sqlite`), Supabase (com a tabela e a operação). Em Python: `sqlite3`, `psycopg2`, `psycopg`, `asyncpg`, `pymysql` e o SQLAlchemy |
 | IA | OpenAI, Anthropic, Google, Mistral, Groq, OpenRouter, DeepSeek, Cohere, Together, modelos locais |
 | Email e mensagens | nodemailer, Resend, SendGrid, Postmark, Mailgun, Brevo, Twilio |
 | Pagamentos | Stripe, com a indicação de modo de teste ou de produção |
@@ -50,12 +58,12 @@ Outras apps Node devem funcionar (Nuxt, SvelteKit, Astro, Remix, NestJS, Fastify
 Os serviços chamados diretamente do browser (por exemplo o Supabase, em muitas apps do Lovable e do Bolt) aparecem como pedidos do browser, sem o passo a passo do servidor.
 
 **Ainda não serve para:**
-- apps em Python, PHP, Go ou Ruby (FastAPI, Flask, Django, Laravel…);
-- sites só com HTML e JavaScript, sem um servidor Node;
+- Django, nem apps em PHP, Go ou Ruby (Laravel, Rails…);
+- sites só com HTML e JavaScript, sem um servidor Node ou Python;
 - partes que correm em Bun, Deno, Cloudflare Workers ou no middleware do Next.js;
 - apps em produção ou que só existem na nuvem.
 
-Precisa do Node.js 24 ou mais recente. Ensaiado em macOS; o Windows ainda não foi ensaiado.
+Precisa do Node.js 24 ou mais recente, também nas apps Python (o codeTAC é instalado pelo npm). Ensaiado em macOS; o Windows ainda não foi ensaiado.
 
 ---
 
@@ -68,6 +76,7 @@ Precisa de três coisas:
    - no GitHub, **Code → Download ZIP**, e descompacte o ficheiro;
    - ou `git clone <endereço>`, se usa o Git.
 3. **Um browser:** Chrome, Edge, Firefox ou Safari.
+4. **Só nas apps Python: o Python 3.12 ou mais recente.** Para verificar, escreva `python3 --version`. Se não tiver, instale-o em [python.org](https://www.python.org/downloads/) (no macOS, também `brew install python`). Se tiver o [uv](https://docs.astral.sh/uv/), o codeTAC usa-o, e ele descarrega o Python que faltar.
 
 **Como abrir o Terminal:**
 - **macOS:** Cmd+Espaço, escreva «Terminal», Enter;
@@ -96,6 +105,8 @@ Se aparecer um erro de permissões (`EACCES`), use `npx codetac` em vez de `code
 
 3. O codeTAC diz o que vai arrancar, por exemplo `Arranque: Vite · npm run dev`.
    - Se faltarem as dependências da app, pergunta se as instala. Carregue em **Enter**, que quer dizer sim.
+   - Numa app Python sem ambiente, pergunta se cria o `.venv` na pasta do projeto e instala as dependências (`requirements.txt`, `pyproject.toml` ou `uv.lock`). **Enter** quer dizer sim.
+   - Se o projeto tiver um `.env.example` e não um `.env`, avisa: muitas apps precisam dessa configuração (copie o ficheiro para `.env` e preencha-o).
    - Se o projeto tiver várias partes, pergunta quais arranca. **Enter** arranca todas.
 4. Quando aparecer **«✓ App pronta em http://localhost:…»**, o browser abre com a sua app.
 5. **Use a app:** clique num botão, numa ligação, envie um formulário.
@@ -148,10 +159,13 @@ Cada linha começa por **✓** (funciona), **!** (atenção) ou **✗** (problem
 
 | Mensagem | O que fazer |
 | --- | --- |
-| «Não encontrei um package.json…» | Está na pasta errada. Vá para a pasta que tem o ficheiro `package.json`, ou indique o arranque: `codetac -- node server.js` |
+| «Não encontrei um package.json…» | Está na pasta errada. Vá para a pasta que tem o ficheiro `package.json` (ou, numa app Python, o `requirements.txt`, o `pyproject.toml` ou o `main.py`/`app.py`), ou indique o arranque: `codetac -- node server.js`, `codetac -- uvicorn main:app` |
 | «A porta 3000 já está ocupada por outro programa…» | Feche o outro programa, por exemplo outra app aberta noutra janela do Terminal. Numa app com uma só parte, o codeTAC muda de porta sozinho |
 | «A app falhou também em modo mínimo» | O problema é da própria app. Muitas vezes faltam as chaves no ficheiro `.env` (Supabase, Firebase…). Veja o `.env.example` ou as instruções do projeto |
 | «A página inicial respondeu com erro 500» | A app arrancou, mas falha. O dossier desse carregamento mostra onde |
+| «…ocupada pelo Recetor AirPlay do macOS» | A porta 5000 do Flask é do AirPlay no macOS. O codeTAC arranca a app noutra porta; para usar a 5000, desligue o «Recetor AirPlay» em Definições do Sistema › Geral › AirDrop e Handoff |
+| «Modo mínimo: Python …» | A app corre num Python anterior ao 3.12. Crie o `.venv` com um Python mais recente (apague o `.venv` e corra `codetac` outra vez) |
+| «O hypercorn (ou o granian) ainda não é reconhecido» | Arranque a app com o uvicorn, por exemplo `codetac -- uvicorn main:app` |
 | A barra não aparece na página | Recarregue a página. Veja se o endereço é o que o codeTAC indicou |
 
 **Comunicar um problema:**
@@ -183,20 +197,31 @@ Guarda o diagnóstico num ficheiro, sem código nem dados da app. Envie-o com um
 | Opção | Para quê |
 | --- | --- |
 | `--script <nome>` | usar outro script do `package.json` |
+| `--parte <pasta>` | num projeto com várias partes, qual arrancar (pode repetir) |
 | `--porta <n>` | a porta da app, se não for descoberta sozinha |
 | `--painel <n>` | a porta do painel (por omissão 4000) |
 | `--minimo` | não seguir as funções do projeto |
 | `--sim` | responder «sim» às perguntas |
 | `--nao-abrir` | não abrir o browser |
-| `-- <comando>` | o comando de arranque, por exemplo `codetac -- node server.js` |
+| `-- <comando>` | o comando de arranque, por exemplo `codetac -- node server.js` ou `codetac -- uvicorn main:app --reload` |
 
 ## 9. Limites
 
 - Os tipos de app que servem e os que não servem estão em [Para que apps serve](#para-que-apps-serve).
 - É para usar em desenvolvimento, no seu computador. Não serve para apps em produção.
-- As partes que não correm no Node não são observadas por dentro. O comando avisa quando as reconhece.
+- As partes que não correm no Node nem no Python não são observadas por dentro. O comando avisa quando as reconhece.
 - No browser, mostra-se o elemento, o componente e o caminho até cada pedido, mas não cada função.
 
+**Nas apps Python:**
+- As funções só são seguidas com o Python 3.12 ou mais recente. Abaixo, modo mínimo: pedidos, fronteiras e browser.
+- A app é encontrada quando o `FastAPI(...)` ou o `Flask(...)` (ou uma fábrica `create_app`) está num ficheiro `.py` até dois níveis de pastas abaixo da pasta indicada. Noutros casos, indique o arranque com `codetac -- <comando>`.
+- A configuração da app (`.env`, base de dados, Redis…) é sua: sem ela, o codeTAC mostra o erro da própria app.
+- As threads criadas à mão (`threading.Thread`) não ficam ligadas ao pedido que as criou; as do FastAPI e do `asyncio` ficam.
+- O Redis, o MongoDB e o Celery ainda não aparecem como fronteiras: o tempo passado neles fica dentro da função que os chamou.
+- As páginas enviadas aos pedaços (stream) não recebem a barra; a ação continua a ser gravada.
+- Com muitas consultas por página, o servidor fica mais lento: numa página com 52 consultas SQL, passou de 1,0 para 2,8 ms. Nas outras apps ensaiadas, o tempo ficou entre 1 e 1,3 vezes o normal.
+- MySQL pelo `mysqlclient` e o Django ainda não foram ensaiados.
+
 ## Licença
 
 [MIT](LICENSE).

package/src/ai.mjs

@@ -326,7 +326,9 @@ export async function answerQuestion({ config, dossier, stepId, question, readCo
   const allowedWords = wordsOf(code?.lines.join('\n'), question, ...lines);
   // Answers may talk about other cases of the code, so conditionals are allowed here.
   const rejected = validateSentence(text, { boundaries: facts.boundaries, allowedWords, knownTables, knownHosts, maxLength: 1500, conditionals: true });
-  return { available: true, known: Boolean(result?.sabe), text, rejected, model: config.model, local: Boolean(config.local), valuesSent: Boolean(detail && withValues) };
+  // With a model outside this machine, the answer says the recorded values were not sent.
+  return { available: true, known: Boolean(result?.sabe), text, rejected, model: config.model, local: Boolean(config.local),
+    valuesSent: Boolean(detail && withValues), valuesWithheld: Boolean(detail && !withValues) };
 }
 
 export function createPurposes({ config, cache, readCode, redact = createRedactor(), limit = Number(process.env.CODETAC_AI_LIMIT || 40) }) {

package/src/boundaries.mjs

@@ -89,6 +89,18 @@ export function classifyHttp({ method, url, headers, body, client }) {
     return { ...base, kind: 'ia', provider: AI[host] ?? (local ? 'modelo local' : `compatível (${host})`), operation: path,
       local: local || undefined, model: typeof json?.model === 'string' ? json.model : undefined };
   }
+  // S3-compatible storage: signed header, or a presigned URL (signature in
+  // the query: SigV4, or SigV2, which boto3 still makes by default). Before
+  // the local case: a local MinIO or LocalStack is S3.
+  if (/^AWS4-HMAC-SHA256/.test(String(headers.authorization ?? '')) || headers['x-amz-content-sha256']
+      || queryKeys.some(key => /^x-amz-(signature|algorithm)$/i.test(key))
+      || (queryKeys.includes('AWSAccessKeyId') && queryKeys.includes('Signature'))) {
+    const virtualHost = host.match(/^(.+?)\.s3[.-]/);
+    const bucket = virtualHost ? virtualHost[1] : parsed.pathname.split('/')[1];
+    const operation = { GET: 'leitura', HEAD: 'verificação', PUT: 'escrita', POST: 'escrita', DELETE: 'remoção' }[method] ?? method;
+    const size = Number(headers['content-length']);
+    return { ...base, kind: 'ficheiros', provider: 'S3', operation, bucket, bytes: Number.isFinite(size) ? size : undefined };
+  }
   if (local) return { ...base, local: true };
   if (host === 'api.stripe.com') {
     const auth = String(headers.authorization ?? '');
@@ -115,15 +127,6 @@ export function classifyHttp({ method, url, headers, body, client }) {
     if (area === 'storage') return { ...base, kind: 'ficheiros', provider: 'Supabase Storage', operation: method, bucket: second === undefined ? first : second };
   }
   if (host === 'api.clerk.com' || host.endsWith('.clerk.accounts.dev')) return { ...base, kind: 'autenticação', provider: 'Clerk' };
-  // S3-compatible storage: signed header, or a presigned URL (signature in the query).
-  if (/^AWS4-HMAC-SHA256/.test(String(headers.authorization ?? '')) || headers['x-amz-content-sha256']
-      || queryKeys.some(key => /^x-amz-(signature|algorithm)$/i.test(key))) {
-    const virtualHost = host.match(/^(.+?)\.s3[.-]/);
-    const bucket = virtualHost ? virtualHost[1] : parsed.pathname.split('/')[1];
-    const operation = { GET: 'leitura', HEAD: 'verificação', PUT: 'escrita', POST: 'escrita', DELETE: 'remoção' }[method] ?? method;
-    const size = Number(headers['content-length']);
-    return { ...base, kind: 'ficheiros', provider: 'S3', operation, bucket, bytes: Number.isFinite(size) ? size : undefined };
-  }
   return base;
 }
 

package/src/browser/bar.js

@@ -218,7 +218,9 @@
       if (leaving && navigator.sendBeacon) navigator.sendBeacon(ENDPOINT, new Blob([body], { type: 'text/plain' }));
       else originalFetch.call(window, ENDPOINT, { method: 'POST', body, keepalive: body.length < 60000, headers: { 'content-type': 'text/plain' } }).catch(() => {});
     } catch {}
-    if (action.trigger || action.requests.length) {
+    // A continuation on a new page counts too: in server-rendered apps (a form
+    // that loads the next page) it is how the bar shows what brought you here.
+    if (action.trigger || action.requests.length || action.segment > 1) {
       recorded.push({ id: action.id, label: labelOf(action), requests: action.requests.length, closedBy });
       if (recorded.length > 30) recorded.shift();
       updateBar(true);