codetac 0.1.0

package/src/detect.mjs

@@ -0,0 +1,198 @@
+// Deteção do projeto (Fase 5): gestor de pacotes, stack, script de arranque e
+// porta provável, sem lista fechada de stacks. O que não se consegue deduzir
+// fica em `missing`, para o comando perguntar ao utilizador.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+
+// Ordem de preferência dos scripts de desenvolvimento.
+const SCRIPTS = ['dev', 'start:dev', 'develop', 'serve', 'dev:server', 'server', 'start'];
+// Stacks conhecidas só para dar um nome e uma porta por omissão; as outras
+// arrancam na mesma, pelo script.
+const STACKS = [
+  { dep: 'next', name: 'Next.js', port: 3000 },
+  { dep: 'nuxt', name: 'Nuxt', port: 3000 },
+  { dep: '@remix-run/dev', name: 'Remix', port: 5173 },
+  { dep: '@react-router/dev', name: 'React Router', port: 5173 },
+  { dep: '@sveltejs/kit', name: 'SvelteKit', port: 5173 },
+  { dep: 'astro', name: 'Astro', port: 4321 },
+  { dep: '@angular/core', name: 'Angular', port: 4200 },
+  { dep: '@nestjs/core', name: 'NestJS', port: 3000 },
+  { dep: 'react-scripts', name: 'Create React App', port: 3000 },
+  { dep: 'fastify', name: 'Fastify', port: 3000 },
+  { dep: 'hono', name: 'Hono', port: 3000 },
+  { dep: 'koa', name: 'Koa', port: 3000 },
+  { dep: 'express', name: 'Express', port: 3000 },
+  { dep: 'vite', name: 'Vite', port: 5173 },
+];
+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']);
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+function readText(path, limit = 200_000) {
+  try { return readFileSync(path, 'utf8').slice(0, limit); } catch { return ''; }
+}
+
+export function packageManager(root) {
+  let folder = root;
+  // Workspaces keep the lockfile at the top; look up to three levels.
+  for (let level = 0; level < 4; level++) {
+    if (existsSync(join(folder, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (existsSync(join(folder, 'yarn.lock'))) return 'yarn';
+    if (existsSync(join(folder, 'bun.lockb')) || existsSync(join(folder, 'bun.lock'))) return 'bun';
+    if (existsSync(join(folder, 'package-lock.json'))) return 'npm';
+    const up = join(folder, '..');
+    if (up === folder) break;
+    folder = up;
+  }
+  return 'npm';
+}
+
+function dependencies(pkg) {
+  return { ...pkg?.dependencies, ...pkg?.devDependencies };
+}
+
+export function stackOf(pkg, script = '') {
+  const deps = dependencies(pkg);
+  // The script names the tool actually used (a project may carry several).
+  const byScript = STACKS.find(stack => new RegExp(`(^|[\\s/"'])${stack.dep.split('/').pop()}(\\s|$)`).test(script) && deps[stack.dep]);
+  return byScript ?? STACKS.find(stack => deps[stack.dep]) ?? null;
+}
+
+// Runtimes other than Node cannot load CodeTAC's hooks.
+export function foreignRuntime(command) {
+  const match = String(command).match(/(?:^|[\s;&|(])(bun|deno|python3?|uvicorn|php|go run|cargo)\b(?!-)/);
+  return match ? match[1] : null;
+}
+
+export function chooseScript(pkg) {
+  const scripts = pkg?.scripts ?? {};
+  for (const name of SCRIPTS) {
+    const command = scripts[name];
+    // A "start" that only serves a production build is still a way to run it,
+    // but a "dev" is preferred (it is first in the list).
+    if (typeof command === 'string' && command.trim()) return { name, command };
+  }
+  return null;
+}
+
+// Port from the script arguments, the .env files, the source, or the stack default.
+export function portOf(root, script, stack) {
+  const fromScript = String(script ?? '').match(/(?:--port[= ]|-p[= ]?|PORT=)(\d{2,5})\b/);
+  if (fromScript) return { value: Number(fromScript[1]), source: 'script' };
+  for (const name of ['.env.development.local', '.env.local', '.env.development', '.env']) {
+    const match = readText(join(root, name)).match(/^\s*(?:export\s+)?(?:APP_)?PORT\s*=\s*["']?(\d{2,5})/m);
+    if (match) return { value: Number(match[1]), source: name };
+  }
+  const configs = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'astro.config.mjs', 'nuxt.config.ts'];
+  for (const name of configs) {
+    const match = readText(join(root, name)).match(/\bport\s*:\s*(\d{2,5})/);
+    if (match) return { value: Number(match[1]), source: name };
+  }
+  for (const name of ENTRIES) {
+    const text = readText(join(root, name));
+    const match = text.match(/PORT\s*(?:\|\||\?\?)\s*["']?(\d{2,5})/) ?? text.match(/\.listen\(\s*(\d{2,5})\b/)
+      ?? text.match(/\bport\s*[:=]\s*(\d{4,5})\b/);
+    if (match) return { value: Number(match[1]), source: name };
+  }
+  if (stack?.port) return { value: stack.port, source: `omissão de ${stack.name}` };
+  return null;
+}
+
+function entryFile(root, pkg) {
+  const main = pkg?.main && existsSync(join(root, pkg.main)) ? pkg.main : null;
+  return main ?? ENTRIES.find(name => existsSync(join(root, name))) ?? null;
+}
+
+// One folder with a package.json: how to start it.
+export function describeFolder(folder, top = folder) {
+  const pkg = readJson(join(folder, 'package.json'));
+  if (!pkg) return null;
+  const manager = packageManager(folder);
+  const script = chooseScript(pkg);
+  const entry = script ? null : entryFile(folder, pkg);
+  const stack = stackOf(pkg, script?.command);
+  const foreign = script ? foreignRuntime(script.command) : null;
+  // A Bun lockfile does not require Bun at run time: the scripts run with Node.
+  const runner = manager === 'bun' || foreign === 'bun' ? 'npm' : manager;
+  let command = null;
+  if (script) command = [runner, 'run', script.name];
+  else if (entry) command = ['node', entry];
+  return {
+    folder, part: relative(top, folder) || '.', name: pkg.name ?? basename(folder), manager, runner,
+    stack: stack?.name ?? null, script, entry, command, foreign,
+    port: portOf(folder, script?.command, stack),
+    installed: existsSync(join(folder, 'node_modules')) || existsSync(join(top, 'node_modules')),
+    workspaces: Boolean(pkg.workspaces) || existsSync(join(folder, 'pnpm-workspace.yaml')),
+  };
+}
+
+function childFolders(root) {
+  const found = [];
+  const visit = (folder, depth) => {
+    let names = [];
+    try { names = readdirSync(folder); } catch { return; }
+    for (const name of names) {
+      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);
+      else if (depth < 1) visit(path, depth + 1);
+      if (depth < 1 && ['apps', 'packages'].includes(name)) visit(path, depth + 1);
+    }
+  };
+  visit(root, 0);
+  return [...new Set(found)];
+}
+
+function devPieces(part) {
+  const pkg = readJson(join(part.folder, 'package.json'));
+  const scripts = pkg?.scripts ?? {};
+  if (scripts.dev) return [];
+  return Object.keys(scripts).filter(name => /^dev:(?!.*(db|test|lint|type|build|seed|migrat))/.test(name)).map(name => {
+    // "cd server && npm run dev" or "npm --prefix server run dev": the piece
+    // lives in a subfolder, with its own dependencies.
+    const sub = scripts[name].match(/^\s*cd\s+([\w./-]+)\s*&&|--prefix[= ]([\w./-]+)|(?:^|\s)-C\s+([\w./-]+)/);
+    const inner = sub ? describeFolder(join(part.folder, sub[1] ?? sub[2] ?? sub[3]), part.folder) : null;
+    const stack = inner?.stack ? { name: inner.stack } : stackOf({ ...pkg, dependencies: {} }, scripts[name]);
+    return { ...part, part: `. (${name})`, script: { name, command: scripts[name] }, command: [part.runner, 'run', name],
+      stack: stack?.name ?? null, port: inner?.port ?? portOf(part.folder, scripts[name], stack), foreign: foreignRuntime(scripts[name]) ?? inner?.foreign ?? null,
+      ...(inner ? { installFolder: inner.folder, installed: inner.installed && existsSync(join(inner.folder, 'node_modules')), manager: inner.manager } : {}) };
+  });
+}
+
+// A folder without package.json but with a server file (node server.js).
+function plainEntry(root) {
+  const entry = ENTRIES.find(name => existsSync(join(root, name)));
+  if (!entry) return null;
+  return { folder: root, part: '.', name: basename(root), manager: 'npm', runner: 'npm', stack: null, script: null, entry,
+    command: ['node', entry], foreign: null, port: portOf(root, '', null), installed: true, workspaces: false };
+}
+
+// The project: the top folder, and the parts that can be started. A top
+// 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);
+  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];
+  else if (parts.length === 1) start = parts;
+  const missing = [];
+  if (!top && !parts.length) missing.push('package');
+  else if (!start.length && parts.length > 1) missing.push('part');
+  else if (!start.length) missing.push('command');
+  return { root, name: top?.name ?? basename(root), top, parts, start, missing };
+}
+
+// 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(' ');
+  return `${part.part === '.' ? '' : `[${part.part}] `}${part.stack ? `${part.stack} · ` : ''}${what}`;
+}

package/src/diagnose.mjs

@@ -0,0 +1,121 @@
+// `codetac diagnostico` (Fase 5): o que está e o que não está a funcionar,
+// em linguagem simples, a partir do projeto, do painel e da última gravação.
+import { registerHooks } from 'node:module';
+import http from 'node:http';
+import { join, relative } from 'node:path';
+import { dataDirectory } from './home.mjs';
+import { detectProject, describeStart } from './detect.mjs';
+import { recordingsOf, summarize } from './recording.mjs';
+import { describeConfig, loadConfig } from './ai.mjs';
+
+const directory = dataDirectory();
+
+const REASONS = {
+  'module-transform-failed': 'ficheiros que não foi possível preparar',
+  'source-map-unreadable': 'ficheiros com source map ilegível',
+  'eval-code-transform-failed': 'blocos de código do bundler que não foi possível preparar',
+  'constructor-skipped': 'construtores de classes (correm, mas não aparecem)',
+  '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)',
+};
+
+function ping(port) {
+  return new Promise(done => {
+    const request = http.get({ host: '127.0.0.1', port, path: '/api/ping', timeout: 1500, headers: { host: `127.0.0.1:${port}` } }, response => {
+      response.resume();
+      done(response.statusCode === 200);
+    });
+    request.on('timeout', () => { request.destroy(); done(false); });
+    request.on('error', () => done(false));
+  });
+}
+
+function panelConfig(port) {
+  return new Promise(done => {
+    http.get({ host: '127.0.0.1', port, path: '/api/config', timeout: 1500, headers: { host: `127.0.0.1:${port}` } }, response => {
+      let body = '';
+      response.on('data', chunk => { body += chunk; });
+      response.on('end', () => { try { done(JSON.parse(body)); } catch { done(null); } });
+    }).on('error', () => done(null));
+  });
+}
+
+export async function diagnose(root, { panelPort = 4000, out = text => process.stdout.write(`${text}\n`) } = {}) {
+  let problems = 0;
+  const ok = text => out(`  ✓ ${text}`);
+  const bad = (text, fix) => { problems++; out(`  ✗ ${text}`); if (fix) out(`      → ${fix}`); };
+  const note = (text, fix) => { out(`  ! ${text}`); if (fix) out(`      → ${fix}`); };
+
+  out(`Diagnóstico do CodeTAC · ${root}\n`);
+  out('Este computador');
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major >= 24 && typeof registerHooks === 'function') ok(`Node ${process.version}: consegue seguir as funções do projeto.`);
+  else if (typeof registerHooks === 'function') note(`Node ${process.version}: funciona, mas o CodeTAC foi verificado no Node 24 ou superior.`, 'Instale o Node 24 ou mais recente.');
+  else bad(`Node ${process.version}: não permite seguir as funções; só o modo mínimo (pedidos e fronteiras).`, 'Instale o Node 24 ou mais recente.');
+
+  out('\nO projeto');
+  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>');
+  for (const part of project.start.length ? project.start : project.parts) {
+    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)`);
+    if (part.foreign) note(`O script usa ${part.foreign}, que não é o Node: essa parte corre, mas não é observada por dentro.`);
+  }
+
+  out('\nO painel');
+  const panelOn = await ping(panelPort);
+  if (panelOn) ok(`Está a correr em http://127.0.0.1:${panelPort}.`);
+  else note(`Não está a correr na porta ${panelPort}.`, 'O comando codetac arranca-o; sozinho: npm run panel, na pasta do CodeTAC.');
+  try {
+    // The running panel's own configuration, else the one it would load.
+    const config = (panelOn && await panelConfig(panelPort)) || describeConfig(await loadConfig({ directory }));
+    ok(`Frases de finalidade: ${config.active ? `${config.model} (${config.provider}${config.local ? ', local: nada sai da máquina' : ', excertos redigidos são enviados'})`
+      : `fixas, geradas dos factos (${config.problem ?? 'sem modelo de IA configurado'})`}.`);
+  } catch {}
+
+  out('\nA última gravação deste projeto');
+  const [last] = recordingsOf(directory, root);
+  if (!last) {
+    note('Ainda não há gravações deste projeto.', 'Arranque com: codetac (na pasta do projeto). Depois volte a correr o diagnóstico.');
+    out(problems ? `\n${problems} problema(s) a resolver.` : '\nNada impede o arranque.');
+    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.`);
+  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.');
+  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.');
+    const failed = summary.failed.length;
+    if (failed) {
+      note(`${failed} ficheiro(s) correm sem ser seguidos (não foi possível prepará-los):`);
+      for (const item of summary.failed.slice(0, 5)) out(`      - ${relative(root, item.file ?? '') || item.file}${item.detail ? `: ${item.detail}` : ''}`);
+    }
+    for (const [reason, count] of summary.limitations) {
+      if (reason === 'module-transform-failed' || reason === 'source-map-unreadable') continue;
+      note(`${REASONS[reason] ?? reason}: ${count}.`);
+    }
+  }
+  if (summary.requests) {
+    ok(`Pedidos gravados: ${summary.requests}. Com funções do projeto: ${summary.withFunctions.size}. Com fronteiras: ${summary.withBoundaries.size}.`);
+    if (!minimal && summary.files && !summary.withFunctions.size) note('Nenhum pedido passou por funções do projeto até agora.',
+      'Normal numa app só de frontend (Vite, páginas estáticas): o servidor só entrega ficheiros; o que interessa está no browser.');
+  } 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.');
+  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?).');
+
+  out(problems ? `\n${problems} problema(s) a resolver.` : '\nTudo o que foi possível verificar está a funcionar.');
+  return problems ? 1 : 0;
+}

package/src/digest.mjs

@@ -0,0 +1,317 @@
+// Vista agrupada do dossiê (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).
+import { boundarySentence, duration, names, texts } from './sentences.mjs';
+
+const STRUCTURE = new Set(['CREATE', 'DROP', 'ALTER', 'TRUNCATE']);
+const WRITES = new Set(['INSERT', 'UPDATE', 'DELETE', 'UPSERT', 'REPLACE', 'MERGE']);
+const TRIVIAL_MS = 5;
+const TRIVIAL_LINES = 10;
+// Requests made by the development tooling, not by the application.
+const DEV_TOOLS = /(\.hot-update\.(json|js)$|\/_next\/webpack-hmr|\/__nextjs_|\/__webpack_hmr|\/@vite\/|\/@react-refresh|\/__vite_ping|\/_next\/static\/webpack\/)/;
+
+export function isDevToolRequest(path) { return DEV_TOOLS.test(path ?? ''); }
+
+function tree(steps) {
+  const ids = new Map(steps.map(step => [step.id, { ...step, children: [] }]));
+  const roots = [];
+  for (const step of steps) {
+    const node = ids.get(step.id);
+    const parent = step.parentId ? ids.get(step.parentId) : null;
+    (parent ? parent.children : roots).push(node);
+  }
+  return roots;
+}
+
+// Everything the subtree of a node did outside the project's code.
+function collect(node, into = { boundaries: [], functions: 0, errors: 0 }) {
+  for (const child of node.children ?? []) {
+    if (child.type === 'boundary') into.boundaries.push(child);
+    else into.functions++;
+    if (child.error) into.errors++;
+    collect(child, into);
+  }
+  return into;
+}
+
+function signature(node) {
+  if (node.type === 'group') return `g:${node.group}:${signature(node.children[0])}`;
+  if (node.type === 'function') return `f:${node.file}:${node.line}`;
+  return `b:${node.kind}:${node.operation}:${(node.tables ?? []).join(',')}:${node.provider ?? ''}:${node.host ?? ''}:${node.method ?? ''}:${node.path ?? ''}`;
+}
+function generated(node, root) {
+  if (node.type !== 'function' || !node.file) return false;
+  const within = root && node.file.startsWith(root + '/') ? node.file.slice(root.length + 1) : node.file;
+  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
+    && (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);
+
+// Groups consecutive siblings; the order of the sequence is kept.
+function group(children, parent, ctx) {
+  const t = texts(ctx.lang);
+  const out = [];
+  let index = 0;
+  while (index < children.length) {
+    const node = children[index];
+    // 1. Database setup: a run of structure commands (M14).
+    if (node.type === 'boundary' && node.kind === 'base-de-dados') {
+      let end = index;
+      while (end < children.length && children[end].type === 'boundary' && children[end].kind === 'base-de-dados') end++;
+      const run = children.slice(index, end);
+      const structure = run.filter(item => STRUCTURE.has(item.operation));
+      if (run.length >= 3 && structure.length * 2 >= run.length) {
+        const counts = {};
+        for (const item of run) counts[item.operation] = (counts[item.operation] ?? 0) + 1;
+        const tables = new Set(run.flatMap(item => item.tables ?? []));
+        const failed = run.filter(item => item.error || item.result?.error).length;
+        const changed = run.filter(item => WRITES.has(item.operation)).reduce((total, item) => total + (item.result?.affectedRows ?? 0), 0);
+        const parentOk = parent && parent.type === 'function' && parent.finished && !parent.error;
+        out.push({ type: 'group', group: 'preparacao-bd', id: `g:${run[0].id}`, count: run.length, durationMs: sum(run), errors: failed,
+          sentence: t.dbSetup(run.length, Object.entries(counts).map(([op, n]) => `${n} ${op}`).join(', '), tables.size, failed, changed, parentOk),
+          children: run });
+        index = end;
+        continue;
+      }
+    }
+    // 2. Bundler glue, two or more in a row (before repetitions: glue often
+    // repeats the same wrapper).
+    let end = index + 1;
+    if (generated(node, ctx.root)) {
+      while (end < children.length && generated(children[end], ctx.root)) end++;
+      if (end - index >= 2) {
+        const run = children.slice(index, end);
+        out.push({ type: 'group', group: 'gerado', id: `g:${node.id}`, count: run.length, durationMs: sum(run), errors: run.filter(item => item.error).length,
+          sentence: t.generated(run.length), children: run });
+        index = end;
+        continue;
+      }
+      end = index + 1;
+    }
+    // 3. The same step repeated in a row.
+    while (end < children.length && signature(children[end]) === signature(node)) end++;
+    if (end - index >= 2) {
+      const run = children.slice(index, end);
+      out.push({ type: 'group', group: 'repeticao', id: `g:${node.id}`, count: run.length, durationMs: sum(run),
+        errors: run.filter(item => item.error).length, sentence: t.repeated(node.purpose.text, run.length), first: node, children: run });
+      index = end;
+      continue;
+    }
+    // 4. Trivial helpers, two or more in a row.
+    if (trivial(node) && !generated(node, ctx.root)) {
+      end = index + 1;
+      while (end < children.length && trivial(children[end]) && !generated(children[end], ctx.root)) end++;
+      if (end - index >= 2) {
+        const run = children.slice(index, end);
+        const fns = [...new Set(run.map(item => item.function))];
+        out.push({ type: 'group', group: 'auxiliares', id: `g:${node.id}`, count: run.length, durationMs: sum(run), errors: run.filter(item => item.error).length,
+          sentence: t.helpers(run.length, names(fns, t.and)), children: run });
+        index = end;
+        continue;
+      }
+    }
+    out.push(node);
+    index++;
+  }
+  return blocks(out, ctx);
+}
+
+// The same sequence of 2 to 6 steps repeated in a row (a loop over records):
+// one line, with every step kept in order for the expansion.
+function blocks(nodes, ctx) {
+  const t = texts(ctx.lang);
+  const out = [];
+  let index = 0;
+  while (index < nodes.length) {
+    let best = null;
+    for (let size = 2; size <= 6 && index + size * 2 <= nodes.length; size++) {
+      const pattern = nodes.slice(index, index + size).map(signature);
+      let times = 1;
+      while (index + (times + 1) * size <= nodes.length
+        && nodes.slice(index + times * size, index + (times + 1) * size).every((node, i) => signature(node) === pattern[i])) times++;
+      if (times >= 2 && (!best || times * size > best.times * best.size)) best = { size, times };
+    }
+    if (!best) { out.push(nodes[index++]); continue; }
+    const run = nodes.slice(index, index + best.size * best.times);
+    const first = nodes.slice(index, index + best.size);
+    const inside = run.flatMap(node => [node, ...collect(node).boundaries]).filter(node => node.type === 'boundary');
+    const reads = [...new Set(inside.filter(item => item.kind === 'base-de-dados' && item.operation === 'SELECT').flatMap(item => item.tables ?? []))];
+    const writes = [...new Set(inside.filter(item => item.kind === 'base-de-dados' && WRITES.has(item.operation)).flatMap(item => item.tables ?? []))];
+    const fns = [...new Set(first.flatMap(node => node.type === 'function' ? [node.function] : node.type === 'group' && node.children[0].type === 'function' ? [node.children[0].function] : []))];
+    const parts = [];
+    if (reads.length) parts.push(t.readPart(names(reads, t.and)));
+    if (writes.length) parts.push(t.writePart(t.writeVerbs.UPDATE, names(writes, t.and)));
+    if (fns.length) parts.push(t.calls(names(fns, t.and)));
+    out.push({ type: 'group', group: 'bloco', id: `g:b:${run[0].id}`, count: run.length, durationMs: sum(run), errors: run.filter(item => item.error || item.errors).length,
+      sentence: t.block(best.times, best.size, parts.join(' · ')), children: run });
+    index += run.length;
+  }
+  return out;
+}
+
+// What a function did, from the boundaries in its subtree and the functions it called.
+function functionSentence(node, ctx) {
+  const t = texts(ctx.lang);
+  const facts = collect(node);
+  const parts = [];
+  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));
+  const reads = [...new Set(db.filter(item => item.operation === 'SELECT').flatMap(item => item.tables ?? []))];
+  if (reads.length) parts.push(t.readPart(names(reads, t.and)));
+  // Writes that changed no rows (or failed) are not presented as changes.
+  const idle = new Set();
+  for (const op of WRITES) {
+    const writes = db.filter(item => item.operation === op);
+    const done = writes.filter(item => !item.error && !item.result?.error && item.result?.affectedRows !== 0);
+    const tables = [...new Set(done.flatMap(item => item.tables ?? []))];
+    if (tables.length) parts.push(t.writePart(t.writeVerbs[op], names(tables, t.and)));
+    for (const item of writes) if (!done.includes(item)) for (const table of item.tables ?? []) if (!tables.includes(table)) idle.add(table);
+  }
+  if (idle.size) parts.push(t.idleWritePart(names([...idle], t.and)));
+  const kinds = kind => facts.boundaries.filter(item => item.kind === kind);
+  const hosts = [...new Set(kinds('http').map(item => item.host))];
+  if (hosts.length) parts.push(t.httpPart(names(hosts, t.and)));
+  const ai = [...new Set(kinds('ia').map(item => item.provider))];
+  if (ai.length) parts.push(t.aiPart(names(ai, t.and)));
+  const mail = kinds('email').length + kinds('mensagem').length;
+  if (mail) parts.push(t.emailPart(mail));
+  const pay = [...new Set(kinds('pagamento').map(item => item.provider))];
+  if (pay.length) parts.push(t.paymentPart(names(pay, t.and)));
+  const files = [...new Set(kinds('ficheiros').map(item => item.operation))];
+  if (files.length) parts.push(t.filePart(names(files, t.and)));
+  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);
+  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);
+  const text = parts.join(' · ');
+  return text[0].toUpperCase() + text.slice(1);
+}
+
+function annotate(node, ctx) {
+  for (const child of node.children) annotate(child, ctx);
+  node.purpose = { text: node.type === 'function' ? functionSentence(node, ctx) : boundarySentence(node, ctx.lang), source: 'factos' };
+  node.children = group(node.children, node, ctx);
+  return node;
+}
+
+function counts(nodes) {
+  let visible = 0;
+  let total = 0;
+  const walk = (list, open) => {
+    for (const node of list) {
+      if (node.type === 'group') {
+        if (open) visible++;
+        walk(node.children, false);
+      } else {
+        total++;
+        if (open) visible++;
+        walk(node.children ?? [], open);
+      }
+    }
+  };
+  walk(nodes, true);
+  return { visible, total };
+}
+
+// Lasting effects of the steps of one or more requests.
+export function effects(dossiers, lang, { cookies = [] } = {}) {
+  const t = texts(lang).effects;
+  const items = [];
+  const add = (key, category, make, amount = 1) => {
+    let found = items.find(item => item.key === key);
+    if (!found) items.push(found = { key, category, n: 0, total: null, make });
+    found.n++;
+    if (amount != null) found.total = (found.total ?? 0) + amount;
+    else found.unknown = true;
+  };
+  let structureOk = 0;
+  let structureFailed = 0;
+  const steps = dossiers.flatMap(dossier => dossier.steps ?? []);
+  for (const step of steps) {
+    if (step.type !== 'boundary') continue;
+    const r = step.result ?? {};
+    const failed = Boolean(step.error || r.error);
+    const table = (step.tables ?? []).join(', ') || '?';
+    if (step.kind === 'base-de-dados' && STRUCTURE.has(step.operation)) {
+      if (failed) structureFailed++; else structureOk++;
+    } else if (step.kind === 'base-de-dados' && WRITES.has(step.operation) && !failed) {
+      const n = r.affectedRows;
+      if (n === 0) add(`none:${step.operation}:${table}`, 'sem-alteracao', (item) => t.noChange(step.operation, table, item.n));
+      else {
+        const make = step.operation === 'INSERT' ? item => t.added(item.unknown ? null : item.total, table)
+          : step.operation === 'UPDATE' ? item => t.changed(item.unknown ? null : item.total, table)
+          : step.operation === 'DELETE' ? item => t.deleted(item.unknown ? null : item.total, table)
+          : () => t.otherWrite(step.operation, table);
+        add(`db:${step.operation}:${table}`, 'base-de-dados', make, n ?? null);
+      }
+    } else if (step.kind === 'email') add(`mail:${step.id}`, 'email', () => t.email(step.to ?? [], step.subject, failed));
+    else if (step.kind === 'mensagem') add(`msg:${step.id}`, 'email', () => t.message(step.provider ?? step.library, failed));
+    else if (step.kind === 'pagamento' && !failed) add(`pay:${step.id}`, 'pagamento', () => t.payment(step.provider, step.operation, step.mode));
+    else if (step.kind === 'ficheiros' && !failed && !['leitura', 'verificação', 'GET', 'HEAD'].includes(step.operation)) {
+      const where = step.bucket ? `${step.provider} ${step.bucket}` : step.path ?? step.provider;
+      add(`file:${step.operation}:${where}`, 'ficheiros', () => t.file(step.operation, where));
+    } else if (step.kind === 'ia') add(`ia:${step.id}`, 'custo', () => t.ai(step.provider, r.model ?? step.model, r.usage, step.costUsd));
+    else if (step.kind === 'http' && !step.local && !failed) {
+      add(`http:${step.method}:${step.host}`, step.method === 'GET' || step.method === 'HEAD' ? 'leitura-externa' : 'externo',
+        item => t.external(step.method, step.host, item.n));
+    }
+  }
+  const set = [...new Set(cookies.filter(item => !item.cleared).map(item => item.name))];
+  const cleared = [...new Set(cookies.filter(item => item.cleared).map(item => item.name))];
+  const result = items.map(item => ({ category: item.category, text: item.make(item) }));
+  if (set.length) result.push({ category: 'browser', text: t.cookieSet(set.join(', ')) });
+  if (cleared.length) result.push({ category: 'browser', text: t.cookieCleared(cleared.join(', ')) });
+  if (structureOk + structureFailed) result.push({ category: 'estrutura', text: t.structure(structureOk, structureFailed) });
+  const lasting = result.filter(item => !['sem-alteracao', 'leitura-externa', 'custo'].includes(item.category));
+  return { items: result, lasting: lasting.length, none: lasting.length ? null : t.none, unseen: t.unseen };
+}
+
+// The grouped view of one request dossier.
+export function digestRequest(dossier, { lang = 'pt-PT' } = {}) {
+  const ctx = { lang, root: dossier.root };
+  const roots = tree(dossier.steps ?? []);
+  const pseudo = { type: 'request', children: roots };
+  for (const node of roots) annotate(node, ctx);
+  const nodes = group(roots, pseudo, ctx);
+  return { nodes, lines: counts(nodes), effects: effects([dossier], lang, { cookies: dossier.request?.cookies ?? [] }),
+    duration: duration(dossier.request?.durationMs, lang) };
+}
+
+// A whole action: every server dossier grouped, development-tool requests
+// grouped (M8), a one-line summary and the effects of all its requests.
+export function digestAction(dossier, { lang = 'pt-PT' } = {}) {
+  const t = texts(lang);
+  const servers = [];
+  const timeline = [];
+  for (const item of dossier.timeline) {
+    for (const server of item.server ?? []) {
+      server.digest = digestRequest(server, { lang });
+      servers.push(server);
+    }
+    const dev = item.type === 'request' && isDevToolRequest(item.browser?.path);
+    const previous = timeline.at(-1);
+    if (dev && previous?.type === 'dev-group') previous.items.push(item);
+    else if (dev) timeline.push({ type: 'dev-group', items: [item] });
+    else timeline.push(item);
+  }
+  for (const item of timeline) if (item.type === 'dev-group') item.sentence = t.devTools(item.items.length);
+  // One line: what was pressed, what the server was asked, what it changed.
+  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));
+  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; });
+  const all = effects(servers, lang, { cookies: servers.flatMap(server => server.request?.cookies ?? []) });
+  const summary = [opening, requests.length ? requests.join(', ') : a.noServer, ...new Set(navigations), changed ? a.screen : a.noScreen].join(' → ');
+  return { timeline, summary, effects: all, lines: servers.reduce((total, server) => total + server.digest.lines.visible, 0) };
+}

package/src/home.mjs

@@ -0,0 +1,15 @@
+// Where CodeTAC keeps its recordings, its database and its configuration
+// (Phase 6): CODETAC_HOME; in a Git checkout of CodeTAC, its own .codetac
+// folder (as in the earlier phases); installed from npm, ~/.codetac.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const install = fileURLToPath(new URL('../', import.meta.url));
+
+export function dataDirectory(env = process.env) {
+  if (env.CODETAC_HOME) return resolve(env.CODETAC_HOME);
+  if (existsSync(join(install, '.git'))) return join(install, '.codetac');
+  return join(homedir(), '.codetac');
+}