codetac 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codetac",
-  "version": "0.1.0",
-  "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,9 +2,15 @@
 
 **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).*
 
-Clica num botão da sua app e o codeTAC mostra um **dossiê** dessa ação:
+![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)
+
+## Para quê
+
+A sua app foi feita por uma IA, ou por outra pessoa, e não sabe ao certo o que acontece quando carrega em «Guardar»? Que funções correm, que tabela é alterada, se sai um email, se o pagamento está em modo de teste ou de produção?
+
+Carregue num botão da sua app e o codeTAC mostra um **dossier** dessa ação:
 - **no browser:** o que foi clicado, o componente e onde está no código;
 - **no servidor:** as funções do seu projeto que correram, pela ordem, com o ficheiro e a linha;
 - **as fronteiras:** base de dados, serviços externos, email, pagamentos, ficheiros, IA;
@@ -12,8 +18,53 @@ Clica num botão da sua app e o codeTAC mostra um **dossiê** dessa ação:
 - **os efeitos permanentes:** linhas gravadas, emails enviados, cookies…;
 - uma frase simples em cada passo a dizer para que serve.
 
+Em qualquer passo, pode abrir o código dessa função e fazer uma pergunta sobre ele.
+
 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) ou em Python (FastAPI ou Flask), a correr no seu computador.** Incluindo as feitas com Lovable, Bolt, v0, Cursor, Replit ou Claude Code.
+
+**Node.js — ensaiado com:**
+- Next.js (incluindo a versão 16);
+- Vite + React;
+- Express;
+- TanStack Start;
+- projetos com frontend e backend separados, e monorepos (npm, pnpm, yarn).
+
+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). 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 |
+| Autenticação | NextAuth, Supabase Auth, Clerk |
+| Ficheiros | disco do computador, S3, Supabase Storage |
+| Outros | qualquer pedido do servidor a um serviço externo, cookies |
+
+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:**
+- 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, também nas apps Python (o codeTAC é instalado pelo npm). Ensaiado em macOS; o Windows ainda não foi ensaiado.
+
 ---
 
 ## 1. Antes de começar
@@ -25,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;
@@ -42,7 +94,7 @@ Confirme com `codetac --version`, que mostra o número da versão.
 
 Se aparecer um erro de permissões (`EACCES`), use `npx codetac` em vez de `codetac` nos passos abaixo. Funciona sem instalar.
 
-## 3. O primeiro dossiê
+## 3. O primeiro dossier
 
 1. No Terminal, vá para a pasta do projeto: escreva `cd ` (com um espaço), arraste a pasta do projeto para a janela do Terminal e carregue em Enter.
 2. Escreva:
@@ -53,17 +105,19 @@ 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.
    - No canto inferior direito da página aparece uma pequena barra com «Gravada: …».
-   - No Terminal aparece «✓ Primeiro dossiê …» com um link.
-6. Carregue na barra, ou abra o link, para ver o dossiê.
+   - No Terminal aparece «✓ Primeiro dossier …» com um link.
+6. Carregue na barra, ou abra o link, para ver o dossier.
 7. Para terminar, volte ao Terminal e carregue em **Ctrl+C**.
 
-Numa app que já conhece, o primeiro dossiê chega normalmente em menos de um minuto.
+Numa app que já conhece, o primeiro dossier chega normalmente em menos de um minuto.
 
-## 4. Ler o dossiê
+## 4. Ler o dossier
 
 - **A frase do topo** resume a ação, por exemplo: «Clique em botão «Add» → POST /api/items (estado 201) → altera o ecrã».
 - **browser → servidor:** cada pedido que a ação fez ao servidor. Por baixo estão as funções do seu projeto que correram.
@@ -105,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 dossiê desse carregamento mostra onde |
+| «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:**
@@ -140,20 +197,30 @@ 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
 
-- Só apps **Node.js** (JavaScript e TypeScript) a correr **no seu computador**, em desenvolvimento.
-- Não serve para apps em produção nem só na nuvem.
-- Partes da app que não correm no Node não são observadas por dentro: Bun, Deno, Cloudflare Workers, o middleware do Next.js. O comando avisa quando as reconhece.
+- 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 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.
-- Windows: ainda não ensaiado.
+
+**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
 

package/src/ai.mjs

@@ -295,7 +295,7 @@ export async function answerQuestion({ config, dossier, stepId, question, readCo
   let step = null;
   let parent = null;
   walk(dossier.digest.nodes, (node, holder) => { if (node.id === stepId) { step = node; parent = holder; } });
-  if (!step) return { available: true, known: false, text: 'Este passo não foi encontrado no dossiê.' };
+  if (!step) return { available: true, known: false, text: 'Este passo não foi encontrado no dossier.' };
   const target = step.type === 'function' ? step : parent?.type === 'function' ? parent : null;
   const code = target ? readCode(dossier.request.run, target.file, target.line, target.endLine) : null;
   const facts = target ? subtree(target) : { boundaries: [step], functions: [] };
@@ -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);
@@ -521,7 +523,7 @@
       '.top{display:flex;gap:6px;align-items:center;padding:6px 8px;background:#18181b;color:#f4f4f5}.top b{margin-right:auto}' +
       '.top button,.top a{all:unset;cursor:pointer;padding:2px 8px;border-radius:5px;color:#e4e4e7}.top button:hover,.top a:hover{background:#3f3f46}' +
       'iframe{border:0;flex:1;width:100%}.msg{padding:16px;color:#27272a}</style>' +
-      '<button class="pill" part="pill" title="CodeTAC: carregue para ver o dossiê da última ação"><span class="dot"></span><span class="label">CodeTAC</span></button>';
+      '<button class="pill" part="pill" title="CodeTAC: carregue para ver o dossier da última ação"><span class="dot"></span><span class="label">CodeTAC</span></button>';
     shadow.querySelector('.pill').addEventListener('click', () => toggleSheet());
     document.documentElement.appendChild(host);
     updateBar(false);
@@ -562,7 +564,7 @@
     }
     shown.innerHTML = '<div class="top"><b></b><button data-go="-1" title="Ação anterior">◀</button><button data-go="1" title="Ação seguinte">▶</button>' +
       '<a target="_blank" rel="noopener" title="Abrir no painel">painel ↗</a><button data-close title="Fechar">✕</button></div>' +
-      '<iframe title="Dossiê da ação"></iframe>';
+      '<iframe title="Dossier da ação"></iframe>';
     shown.querySelector('b').textContent = (index + 1) + '/' + recorded.length + ' · ' + item.label;
     shown.querySelector('a').href = panel + '/?action=' + encodeURIComponent(item.id);
     shown.querySelector('iframe').src = url;