codetac 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deltaXmodules
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "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.",
+  "keywords": [
+    "debug",
+    "trace",
+    "understand",
+    "nodejs",
+    "nextjs",
+    "vite",
+    "express",
+    "ai-generated",
+    "vibe-coding",
+    "dossier"
+  ],
+  "license": "MIT",
+  "author": "deltaXmodules",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deltaxmodules/codetacvibe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/deltaxmodules/codetacvibe/issues"
+  },
+  "homepage": "https://github.com/deltaxmodules/codetacvibe#readme",
+  "type": "module",
+  "bin": {
+    "codetac": "src/cli.mjs"
+  },
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "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",
+    "test:performance": "node scripts/benchmark-functions.mjs",
+    "panel": "node src/panel.mjs",
+    "test:browser": "node scripts/accept-browser.mjs docs/aceitacao-browser-exemplo.json",
+    "codetac": "node src/cli.mjs"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.128.0",
+    "@jridgewell/trace-mapping": "^0.3.31",
+    "acorn": "^8.18.0",
+    "acorn-walk": "^8.3.5",
+    "magic-string": "^1.4.1"
+  },
+  "devDependencies": {
+    "express": "^5.2.1",
+    "next": "^16.3.6",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "vite": "^8.3.0"
+  }
+}

package/readme.md

@@ -0,0 +1,172 @@
+# codeTAC
+
+**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).*
+
+Clica num botão da sua app e o codeTAC mostra um **dossiê** 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;
+- **o que mudou no ecrã;**
+- **os efeitos permanentes:** linhas gravadas, emails enviados, cookies…;
+- uma frase simples em cada passo a dizer para que serve.
+
+Tudo corre no seu computador. O código da app não é alterado.
+
+---
+
+## 1. Antes de começar
+
+Precisa de três coisas:
+
+1. **Node.js 24 ou mais recente.** Para verificar, abra o Terminal e escreva `node -v`. Tem de aparecer `v24` ou um número maior. Se não aparecer, instale a versão LTS em [nodejs.org](https://nodejs.org).
+2. **O projeto da sua app no seu computador.** Se a app foi feita no Lovable, Bolt, v0 ou Replit, ligue-a ao GitHub e descarregue-a:
+   - 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.
+
+**Como abrir o Terminal:**
+- **macOS:** Cmd+Espaço, escreva «Terminal», Enter;
+- **Windows:** menu Iniciar, escreva «PowerShell», Enter. No Windows, o codeTAC ainda não foi ensaiado.
+
+## 2. Instalar
+
+No Terminal:
+
+```sh
+npm install -g codetac
+```
+
+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ê
+
+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:
+
+   ```sh
+   codetac
+   ```
+
+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.
+   - 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ê.
+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.
+
+## 4. Ler o dossiê
+
+- **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.
+- **Etiquetas coloridas** («base de dados», «HTTP», «email»…): os pontos em que a app fala com o exterior.
+- **▸** abre um grupo, por exemplo repetições ou preparação da base de dados. **Ver tudo** mostra a sequência completa.
+- **Clique numa função** para ver o código dela e fazer uma pergunta sobre esse passo.
+- **pedir detalhe:** a partir da ação seguinte, essa função grava também os valores que recebeu e devolveu, e as linhas que correram.
+- **Efeitos permanentes:** o que ficou depois da ação (linhas gravadas, emails, cookies). «Nenhum efeito permanente observado» quer dizer que a ação só consultou.
+- **Modo mínimo** (faixa amarela): o codeTAC não conseguiu seguir as funções do projeto e mostra só os pedidos, as fronteiras e o browser. A faixa diz porquê.
+
+## 5. Explicações com IA (opcional)
+
+Sem configuração:
+- se o [Ollama](https://ollama.com) estiver a correr neste computador, o codeTAC usa-o, e nada sai da máquina;
+- se não estiver, as frases são geradas só a partir do que foi gravado.
+
+Para usar a Anthropic ou a OpenAI, crie o ficheiro `~/.codetac/ia.json`:
+
+```json
+{ "provider": "anthropic", "key": "a-sua-chave" }
+```
+
+Para a OpenAI: `{ "provider": "openai", "model": "gpt-5.4-mini", "key": "…" }`.
+
+Com um modelo na nuvem, são enviados excertos do código das funções, depois de retirados os segredos. Os valores gravados nunca são enviados. O painel indica o que está a ser usado.
+
+- **«IA»** ao lado de uma frase: a frase veio do modelo e bate certo com o que foi gravado.
+- **«IA rejeitada»:** a frase do modelo dizia algo que não foi observado. Foi trocada pela frase feita a partir dos factos. Passe o rato por cima para ver o motivo.
+
+## 6. Quando algo não funciona
+
+Com a app a correr, noutra janela do Terminal e na mesma pasta:
+
+```sh
+codetac diagnostico
+```
+
+Cada linha começa por **✓** (funciona), **!** (atenção) ou **✗** (problema), com o que fazer.
+
+| 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` |
+| «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 barra não aparece na página | Recarregue a página. Veja se o endereço é o que o codeTAC indicou |
+
+**Comunicar um problema:**
+
+```sh
+codetac relatorio
+```
+
+Guarda o diagnóstico num ficheiro, sem código nem dados da app. Envie-o com uma descrição do que fez e do que esperava em [github.com/deltaxmodules/codetacvibe/issues](https://github.com/deltaxmodules/codetacvibe/issues).
+
+## 7. Privacidade
+
+- Tudo fica no seu computador, em `~/.codetac` (pode ser outra pasta, com `CODETAC_HOME`).
+- Antes de gravar, são retirados os segredos: passwords, tokens, chaves, emails e telefones.
+- Por omissão não se gravam valores, só nomes, ficheiros e linhas. Os valores só são gravados nas funções onde pedir detalhe.
+- O painel só responde neste computador (`127.0.0.1`).
+
+## 8. Comandos
+
+| Comando | O que faz |
+| --- | --- |
+| `codetac [pasta]` | Arranca a app com o codeTAC |
+| `codetac diagnostico [pasta]` | Explica o que funciona e o que não funciona |
+| `codetac relatorio [pasta]` | Guarda o diagnóstico para enviar com uma incidência |
+| `codetac ajuda` | Todas as opções |
+
+**Opções:**
+
+| Opção | Para quê |
+| --- | --- |
+| `--script <nome>` | usar outro script do `package.json` |
+| `--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` |
+
+## 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.
+- 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
+
+[MIT](LICENSE).
+
+## Desenvolvimento
+
+```sh
+git clone https://github.com/deltaxmodules/codetacvibe.git
+cd codetacvibe
+npm ci
+npm test
+node src/cli.mjs ajuda
+```
+
+Num checkout Git, as gravações ficam em `.codetac/`, dentro do repositório.

package/src/action-view.mjs

@@ -0,0 +1,104 @@
+// Action dossier as shown to a person: the store's dossier with the browser
+// positions resolved to project files (through the application's source maps).
+import { sep } from 'node:path';
+import { createResolver } from './origins.mjs';
+
+export function createActionView(store, resolver = createResolver()) {
+  const browserFiles = new Map();
+  // Browser files that may be shown: project files found by resolving the
+  // positions of a recorded action of that run.
+  const LIBRARIES_OF_REACT = new Set(['react', 'react-dom', 'scheduler', 'react-server-dom-webpack', 'react-server-dom-turbopack']);
+
+  function shortFile(root, file) {
+    return root && file && file.startsWith(root + sep) ? file.slice(root.length + 1) : file;
+  }
+  function allowBrowserFile(run, file) {
+    if (!browserFiles.has(run)) browserFiles.set(run, new Set());
+    browserFiles.get(run).add(file);
+  }
+  // React itself, also when a framework ships its own copy (next/dist/compiled/react).
+  function reactInternal(frame) {
+    return LIBRARIES_OF_REACT.has(frame.library) || /\/compiled\/(react|react-dom|react-server-dom-[\w-]+|scheduler)\//.test(frame.file ?? '')
+      || /^(exports\.)?(jsxDEV|jsxs?|createElement|fakeJSXCallSite)$/.test(frame.fn ?? '');
+  }
+  // Where the element was written: the first frame outside React itself.
+  function creation(frames, root, run) {
+    const frame = frames.find(item => item.resolved && !reactInternal(item));
+    if (!frame) return null;
+    if (frame.project) {
+      allowBrowserFile(run, frame.file);
+      return { project: true, fn: frame.fn ?? null, file: frame.file, short: shortFile(root, frame.file), line: frame.line };
+    }
+    return { project: false, library: frame.library ?? null };
+  }
+  // The project functions on the way to a request, outermost first.
+  function chain(frames, root, run) {
+    const result = [];
+    for (const frame of [...frames].reverse()) {
+      if (!frame.project) continue;
+      const previous = result.at(-1);
+      if (previous && previous.file === frame.file && previous.line === frame.line) continue;
+      allowBrowserFile(run, frame.file);
+      result.push({ fn: frame.fn ?? '(anónima)', file: frame.file, short: shortFile(root, frame.file), line: frame.line, resolved: frame.resolved });
+    }
+    const libraries = [...new Set(frames.filter(frame => frame.library && !reactInternal(frame)).map(frame => frame.library))];
+    return { chain: result, libraries, unresolved: frames.length > 0 && frames.every(frame => !frame.resolved) };
+  }
+
+  async function resolvedAction(id) {
+    store.ingest();
+    const dossier = store.actionDossier(id);
+    if (!dossier) return null;
+    const context = { origin: dossier.origin, root: dossier.root, scripts: dossier.scripts };
+    const resolve = async frames => {
+      if (!dossier.root) return [];
+      return Promise.all((frames ?? []).map(async frame => {
+        // Script URLs carry the port of that run, so the key is unique to it.
+        const key = JSON.stringify([dossier.root, frame.url ?? frame.file, frame.line, frame.column]);
+        const cached = store.cachedOrigin?.(key);
+        if (cached) return { ...cached, fn: frame.fn || cached.fn };
+        if (!dossier.origin && !frame.file) return { ...frame, resolved: false };
+        const result = await resolver.resolveFrame(frame, context);
+        if (result.resolved) store.cacheOrigin?.(key, result);
+        return result;
+      }));
+    };
+    const run = dossier.run;
+    for (const item of dossier.timeline) {
+      if (item.type === 'trigger' && item.trigger.component) {
+        const component = item.trigger.component;
+        component.origin = creation(await resolve(component.frames), dossier.root, run);
+        delete component.frames;
+        // When the element comes from a library component (a router link, a
+        // UI kit button), the first owner written in the project is named too.
+        for (const owner of component.owners ?? []) {
+          owner.origin = creation(await resolve(owner.frames), dossier.root, run);
+          delete owner.frames;
+        }
+        if (!component.origin?.project) {
+          const index = (component.owners ?? []).findIndex(owner => owner.origin?.project);
+          // owners[index] was written in the project, inside owners[index + 1].
+          if (index >= 0) component.project = { name: component.owners[index + 1]?.name ?? null, via: component.owners[index].name,
+            origin: component.owners[index].origin };
+        }
+      }
+      if (item.type === 'request') {
+        Object.assign(item.browser, chain(await resolve(item.browser.frames), dossier.root, run));
+        delete item.browser.frames;
+      }
+      if (item.type === 'screen') {
+        for (const key of ['stateChanged', 'mounted', 'unmounted']) {
+          for (const component of item.screen[key] ?? []) {
+            component.origin = creation(await resolve(component.frames), dossier.root, run);
+            delete component.frames;
+          }
+        }
+      }
+    }
+    delete dossier.scripts;
+    return dossier;
+  }
+
+
+  return { resolvedAction, browserFile: (run, file) => Boolean(browserFiles.get(run)?.has(file)) };
+}