codetac 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codetac",
-  "version": "0.1.0",
+  "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.",
   "keywords": [
     "debug",

package/readme.md

@@ -4,7 +4,13 @@
 
 *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).*
 
-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,45 @@ 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), a correr no seu computador.** Incluindo as feitas com Lovable, Bolt, v0, Cursor, Replit ou Claude Code.
+
+**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).
+
+**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) |
+| 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:**
+- apps em Python, PHP, Go ou Ruby (FastAPI, Flask, Django, Laravel…);
+- sites só com HTML e JavaScript, sem um servidor Node;
+- 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.
+
 ---
 
 ## 1. Antes de começar
@@ -42,7 +85,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:
@@ -57,13 +100,13 @@ Se aparecer um erro de permissões (`EACCES`), use `npx codetac` em vez de `code
 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.
@@ -108,7 +151,7 @@ Cada linha começa por **✓** (funciona), **!** (atenção) ou **✗** (problem
 | «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` |
 | «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 |
 | 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:**
@@ -149,11 +192,10 @@ Guarda o diagnóstico num ficheiro, sem código nem dados da app. Envie-o com um
 
 ## 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 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.
 
 ## 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: [] };

package/src/browser/bar.js

@@ -521,7 +521,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 +562,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;

package/src/cli.mjs

@@ -491,13 +491,13 @@ 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.`);
+  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 {
-    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 +511,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

package/src/diagnose.mjs

@@ -94,7 +94,7 @@ export async function diagnose(root, { panelPort = 4000, out = text => process.s
   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):`);

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).

package/src/panel.mjs

@@ -202,7 +202,7 @@ const page = `<!doctype html>
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>CodeTAC — dossiês</title>
+<title>CodeTAC — dossiers</title>
 <style>
 :root { --bg:#f7f7f5; --panel:#fff; --text:#1d1d1b; --muted:#6b6b66; --line:#e4e3de; --accent:#2f5bd3;
   --db:#0f7b5f; --http:#6a4bc4; --ia:#b4531f; --mail:#1f73b4; --pay:#9b2c86; --file:#7a6a12; --auth:#3d6b2f; --error:#c0392b; --code:#f1f0ec;