@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/scripts/revisar-entrega/tests/TEST.mjs

@@ -0,0 +1,249 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { checkReview, prepareReview, sealReview, specCriteria } from '../SCRIPT.mjs';
+import { projectRoot } from '../../lib/runtime.mjs';
+
+function fixture(t) {
+  mkdirSync(join(projectRoot, '.agent-tests'), { recursive: true });
+  const root = mkdtempSync(join(projectRoot, '.agent-tests/review-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const git = (...args) => {
+    const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr); return result.stdout;
+  };
+  git('init', '-q');
+  const put = (file, body) => { mkdirSync(dirname(join(root, file)), { recursive: true }); writeFileSync(join(root, file), body); };
+  put('.gitignore', '/.agent-tests/\n'); put('README.md', '# Projeto\n'); put('src/main.mjs', 'export const value=1;\n');
+  put('spec.md', '# Spec\n\n## Critérios de aceite\n\n| ID | Resultado |\n| --- | --- |\n| AC-001 | Um |\n| AC-002 | Dois |\n\n## Dependências\n\nNenhuma.\n');
+  return { root, git, put };
+}
+
+function approved(t, options = {}, setup = () => {}, seal = true) {
+  const f = fixture(t);
+  setup(f);
+  const made = prepareReview({ root: f.root, id: 'mudanca', execution: 'exec-1', scope: ['src/main.mjs'], spec: 'spec.md', ...options });
+  const report = made.report;
+  for (const item of report.documentation) Object.assign(item, { decision: 'no-impact', reason: 'Comportamento externo preservado; revisado.' });
+  const proof = '.agent-tests/mudanca/exec-1/test.txt'; f.put(proof, 'teste real de fixture passou\n');
+  for (const item of report.validation) Object.assign(item, { method: 'node --test', prerequisite: 'Node 24', assertion: 'Resultado esperado presente', evidence: [proof], status: 'passed' });
+  report.review = { status: 'approved', reviewer: 'revisor-independente', findings: [] };
+  const save = () => f.put(made.file, JSON.stringify(report, null, 2)); save();
+  if (seal) sealReview(made.file, { root: f.root });
+  return { ...f, ...made, save, proof };
+}
+
+test('aprova relatorio completo e liga spec, documentos e evidencias ignoradas', t => {
+  const f = approved(t);
+  assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+  assert.equal(f.report.validation.length, 2);
+  assert.ok(f.report.snapshot.files.some(item => item.path === 'README.md'));
+  assert.ok(f.report.snapshot.files.some(item => item.path === 'spec.md'));
+  assert.equal(f.git('ls-files', '--', '.agent-tests').trim(), '');
+});
+
+test('instrucoes existentes entram na revisao e mudancas posteriores invalidam o selo', async t => {
+  for (const file of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) await t.test(file, t => {
+    const f = approved(t, {}, f => f.put(file, '# Instrucoes\n'));
+    assert.ok(f.report.documentation.some(item => item.path === file));
+    assert.ok(f.report.snapshot.files.some(item => item.path === file));
+    f.put(file, '# Instrucoes alteradas\n');
+    assert.throws(() => checkReview(f.file, { root: f.root }), /mudaram/);
+  });
+});
+
+test('instrucoes criadas apos o preparo exigem novo snapshot mesmo em escopo limitado', async t => {
+  for (const file of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) await t.test(file, t => {
+    const f = approved(t, {}, () => {}, false);
+    f.put(file, '# Novas instrucoes\n');
+    f.report.documentation.push({ path: file, decision: 'no-impact', reason: 'Revisado apos o preparo.' });
+    f.save();
+    assert.throws(() => sealReview(f.file, { root: f.root }), /Documentos obrigatorios mudaram/);
+  });
+});
+
+test('relatorio inicial nao aprova entrega nem sobrescreve evidencias anteriores', t => {
+  const f = fixture(t);
+  const options = { root: f.root, id: 'mudanca', execution: 'exec-1', scope: ['src/main.mjs'] };
+  const result = prepareReview(options);
+  assert.throws(() => checkReview(result.file, { root: f.root }), /pendente|invalida/);
+  assert.throws(() => prepareReview(options), /ja existe/);
+});
+
+test('mudanca de codigo, spec ou documento depois do snapshot exige nova revisao', async t => {
+  for (const file of ['src/main.mjs', 'spec.md', 'README.md']) await t.test(file, t => {
+    const f = approved(t); f.put(file, readFileSync(join(f.root, file), 'utf8') + '\nMudanca posterior.');
+    assert.throws(() => checkReview(f.file, { root: f.root }), /mudaram/);
+  });
+});
+
+test('em modo git um novo arquivo elegivel invalida a revisao', t => {
+  const f = approved(t, { scope: [] });
+  f.put('novo.mjs', 'export {};');
+  assert.throws(() => checkReview(f.file, { root: f.root }), /mudaram/);
+});
+
+test('todos os criterios precisam resultado e prova; nao executado nao e aprovado', async t => {
+  for (const status of ['pending', 'failed', 'not-run', 'not-applicable']) await t.test(status, t => {
+    const f = approved(t); f.report.validation[0].status = status; f.save();
+    assert.throws(() => checkReview(f.file, { root: f.root }), /sem prova/);
+  });
+  await t.test('criterio ausente', t => {
+    const f = approved(t); f.report.validation.pop(); f.save();
+    assert.throws(() => checkReview(f.file, { root: f.root }), /sem resultado/);
+  });
+});
+
+test('provas vazias, fora do diretorio e forcadas no Git sao recusadas', async t => {
+  await t.test('vazia', t => { const f = approved(t); f.put(f.proof, ''); assert.throws(() => checkReview(f.file, { root: f.root }), /vazia/); });
+  await t.test('fora', t => { const f = approved(t); f.report.validation[0].evidence = ['README.md']; f.save(); assert.throws(() => checkReview(f.file, { root: f.root }), /Evidencia deve/); });
+  await t.test('versionada', t => { const f = approved(t); f.git('add', '-f', f.proof); assert.throws(() => checkReview(f.file, { root: f.root }), /indice Git/); });
+});
+
+test('sem impacto exige motivo; omitir documento ou deixar achado aberto bloqueia', async t => {
+  await t.test('motivo', t => { const f = approved(t); f.report.documentation[0].reason = ''; f.save(); assert.throws(() => checkReview(f.file, { root: f.root }), /documentacao/); });
+  await t.test('documento', t => { const f = approved(t); f.report.documentation = []; f.save(); assert.throws(() => checkReview(f.file, { root: f.root }), /sem revisao/); });
+  await t.test('achado', t => { const f = approved(t); f.report.review.findings.push({ id: 'R1', description: 'Correcao necessaria', status: 'open' }); f.save(); assert.throws(() => checkReview(f.file, { root: f.root }), /abertos/); });
+});
+
+test('caminhos perigosos e relatorios fora de local ignorado sao recusados', t => {
+  const f = fixture(t);
+  for (const scope of [['../fora'], ['.git/config']]) assert.throws(() => prepareReview({ root: f.root, id: 'mudanca', scope }), /fora do escopo/);
+  f.put('.gitignore', '');
+  assert.throws(() => prepareReview({ root: f.root, id: 'mudanca', scope: ['src/main.mjs'] }), /ignorado/);
+});
+
+test('links simbolicos nao viram prova ou documento autorizado', t => {
+  const f = approved(t); const target = '.agent-tests/mudanca/exec-1/link.txt';
+  try { symlinkSync(join(f.root, f.proof), join(f.root, target)); }
+  catch (error) { if (['EPERM', 'EACCES'].includes(error.code)) return t.skip('Sem permissao de symlink.'); throw error; }
+  f.report.validation[0].evidence = [target]; f.save();
+  assert.throws(() => checkReview(f.file, { root: f.root }), /simbolico/);
+});
+
+test('spec sem IDs claros nao passa pelo preparo', () => {
+  assert.throws(() => specCriteria('## Critérios de aceite\n\nFunciona.\n'), /AC-001/);
+  assert.deepEqual(specCriteria('## Critérios de aceite\nAC-001\nAC-001\n\n## Referências\nAC-999'), ['AC-001']);
+});
+
+test('placeholders no plano nao contam como validacao definida', t => {
+  const f = approved(t); f.report.validation[0].assertion = 'A definir.'; f.save();
+  assert.throws(() => checkReview(f.file, { root: f.root }), /incompleto/);
+});
+
+test('documento extra nao Markdown permanece obrigatorio e protegido pelo snapshot', t => {
+  const f = fixture(t); f.put('api/openapi.yaml', 'openapi: 3.1.0\n');
+  const made = prepareReview({ root: f.root, id: 'mudanca', execution: 'extra', scope: ['src/main.mjs'], documents: ['api/openapi.yaml'] });
+  assert.ok(made.report.snapshot.documents.includes('api/openapi.yaml'));
+  assert.ok(made.report.snapshot.files.some(file => file.path === 'api/openapi.yaml'));
+  made.report.documentation = made.report.documentation.filter(item => item.path !== 'api/openapi.yaml');
+  for (const item of made.report.documentation) Object.assign(item, { decision: 'no-impact', reason: 'Revisado sem alteracao.' });
+  f.put(made.file, JSON.stringify(made.report));
+  assert.throws(() => checkReview(made.file, { root: f.root }), /Documento sem revisao/);
+});
+
+test('spec e documento de referencia nao podem ser artefatos ignorados', t => {
+  const f = fixture(t); f.put('.agent-tests/spec.md', readFileSync(join(f.root, 'spec.md')));
+  assert.throws(() => prepareReview({ root: f.root, id: 'mudanca', spec: '.agent-tests/spec.md' }), /versionavel/);
+  assert.throws(() => prepareReview({ root: f.root, id: 'mudanca', documents: ['.agent-tests/relatorio.txt'] }), /versionavel/);
+});
+
+test('remover referencia da spec do relatorio nao remove sua obrigatoriedade', t => {
+  const f = approved(t); f.report.spec = null; f.save();
+  assert.throws(() => checkReview(f.file, { root: f.root }), /Baseline|referencias alteradas/);
+});
+
+test('indice Git precisa corresponder ao codigo testado antes de commit', t => {
+  const f = approved(t, {}, f => {
+    f.git('add', 'src/main.mjs');
+    f.put('src/main.mjs', 'export const value=2;\n');
+  }, false);
+  assert.throws(() => checkReview(f.file, { root: f.root }), /Indice Git difere/);
+  f.git('add', 'src/main.mjs');
+  sealReview(f.file, { root: f.root });
+  assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+});
+
+test('alterar evidencia apos a aprovacao invalida o selo', t => {
+  const f = approved(t); f.put(f.proof, 'TESTE FALHOU\n');
+  assert.throws(() => checkReview(f.file, { root: f.root }), /apos selar/);
+  assert.throws(() => sealReview(f.file, { root: f.root }), /apos selar/);
+});
+
+test('remover spec e criterios do JSON nao altera a baseline do preparo', t => {
+  const f = approved(t);
+  f.report.spec = null; f.report.snapshot.spec = null;
+  f.report.snapshot.files = f.report.snapshot.files.filter(item => item.path !== 'spec.md');
+  f.report.snapshot.documents = f.report.snapshot.documents.filter(path => path !== 'spec.md');
+  f.report.validation.pop(); f.save();
+  assert.throws(() => checkReview(f.file, { root: f.root }), /Baseline/);
+});
+
+test('check exige selo sem permitir bypass pela API', t => {
+  const f = approved(t, {}, () => {}, false);
+  assert.throws(() => checkReview(f.file, { root: f.root, requireSeal: false }), /nao selada/);
+  sealReview(f.file, { root: f.root });
+  assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+});
+
+function stageUntrack(f, file = 'generated.md', ignore = true) {
+  f.put(file, '# Saida local\n');
+  f.git('add', '-f', '--', file);
+  f.git('-c', 'user.name=Test User', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=disabled-hooks', 'commit', '-q', '-m', 'test: fixture base');
+  f.git('rm', '--cached', '--', file);
+  if (ignore) f.put('.git/info/exclude', `/${file}\n`);
+}
+
+test('desindexação real registra ação e hash físico sem exigir documento local', async t => {
+  for (const scope of [[], ['generated.md']]) await t.test(scope.length ? 'scope' : 'git', t => {
+    const f = approved(t, { scope }, f => stageUntrack(f));
+    const file = f.report.snapshot.files.find(file => file.path === 'generated.md');
+    assert.equal(file.indexAction, 'untrack'); assert.match(file.sha256, /^[a-f0-9]{64}$/);
+    assert.equal(f.report.documentation.some(item => item.path === 'generated.md'), false);
+    assert.ok(existsSync(join(f.root, 'generated.md')));
+    assert.equal(f.git('ls-files', 'generated.md'), '');
+    assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+  });
+});
+
+test('desindexação sem ignore continua bloqueada em git e scope', async t => {
+  for (const scope of [[], ['generated.md']]) await t.test(scope.length ? 'scope' : 'git', t => {
+    assert.throws(() => approved(t, { scope }, f => stageUntrack(f, 'generated.md', false)), /Indice Git difere/);
+  });
+});
+
+test('mudanças no arquivo, índice ou ignore invalidam a revisão de desindexação', async t => {
+  const cases = [
+    ['conteudo', f => f.put('generated.md', '# Editado depois\n')],
+    ['indice', f => f.git('add', '-f', 'generated.md')],
+    ['ignore', f => f.put('.git/info/exclude', '')],
+    ['arquivo removido', f => rmSync(join(f.root, 'generated.md'))],
+  ];
+  for (const [name, change] of cases) await t.test(name, t => {
+    const f = approved(t, { scope: [] }, f => stageUntrack(f));
+    change(f);
+    assert.throws(() => checkReview(f.file, { root: f.root }), /mudaram|desindexacao/);
+  });
+});
+
+test('entradas ignoradas fora do índice não entram nos documentos obrigatórios', t => {
+  const f = approved(t, {}, f => {
+    f.put('AGENTS.md', '# Gerado\n'); f.put('CLAUDE.md', '# Gerado\n'); f.put('GEMINI.md', '# Gerado\n');
+    f.put('.git/info/exclude', '/AGENTS.md\n/CLAUDE.md\n/GEMINI.md\n');
+  });
+  for (const name of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) assert.equal(f.report.documentation.some(item => item.path === name), false);
+  assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+});
+
+test('documentos rastreados permanecem obrigatórios mesmo com regra de ignore', t => {
+  const f = approved(t, {}, f => {
+    f.put('AGENTS.md', '# Instrução versionada\n');
+    f.git('add', 'AGENTS.md', 'spec.md');
+    f.put('.git/info/exclude', '/AGENTS.md\n/spec.md\n');
+  });
+  assert.ok(f.report.documentation.some(item => item.path === 'AGENTS.md'));
+  assert.ok(f.report.documentation.some(item => item.path === 'spec.md'));
+  assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+});

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -0,0 +1,41 @@
+---
+description: Gera catálogos e apontamentos a partir da origem compartilhada.
+---
+
+# Sincronizar agentes
+
+```sh
+node .pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs --check
+node .pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs --force
+node --test .pbai4devs/scripts/sincronizar-agentes/tests/TEST.mjs
+```
+
+`--check` só confere; a execução normal atualiza os recursos. `--force` salva
+conflitos em `.agent-tests/` antes de reparar os caminhos gerenciados.
+
+Metadados vêm da fonte ou do YAML nativo declarado no manifesto. Regras exigem
+`trigger` válido; `glob` exige `globs`. Origens nativas precisam pertencer ao
+catálogo; resultados, caches e pastas temporárias não entram nos índices.
+
+`espelhos.conf` define `agente|pasta|layout`, pode ajustar cada tipo com
+`formato|pasta|tipo|formato` e registrar `descoberta|.agents|antigravity`.
+`agrupado` preserva a árvore; `plano` retira categorias; `arquivo` preserva
+categorias e usa `nome.md`. `mdc`, `instrucoes`, `prompt` e `agente` produzem as
+extensões nativas. A descoberta gera os três manifestos JSON do Antigravity.
+Veja os motivos e limites em [Compatibilidade](../../COMPATIBILIDADE.md).
+
+Sem manifesto, o sincronizador gera a política de
+`templates/clients/ADAPTERS.json`, usando a seleção salva ou `all`.
+Após a instalação, depende somente de Node e do hub local, sem o pacote npm.
+Ele respeita os clientes escolhidos, sem recriar os desmarcados. Para trocar
+a seleção, use `agentdevkit agents <lista>`; não edite o manifesto gerado.
+
+Os derivados ficam locais: catálogos, manifesto, estado e apontamentos são
+excluídos pelo Git. O bloco em `.git/info/exclude` preserva regras próprias;
+sem Git, usa um bloco na raiz que migra ao executar depois de `git init`.
+Raízes dedicadas são locais por completo; `.github` e `.vscode` excluem somente
+os arquivos gerados. Conteúdo próprio permanece no disco e não é desindexado
+sem comprovação de propriedade do kit.
+Entradas novas usam os templates; hashes em `estado/derived.json` permitem
+atualizar apenas arquivos integralmente gerados, preservando alterações humanas.
+`--check` também acusa derivados ainda rastreados; não altera o índice.