@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/scripts/testar-maturidade/assets/http-api.test.mjs.template

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import test from 'node:test';
+import { createApplication } from '__SERVER_IMPORT__';
+
+test('AC-001: HTTP health returns the expected state', async t => {
+  const server = createApplication();
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  t.after(() => new Promise(resolve => server.close(resolve)));
+  const response = await fetch(`http://127.0.0.1:${server.address().port}/health`);
+  assert.equal(response.status, 200);
+  assert.deepEqual(await response.json(), { status: 'ok' });
+});
+
+test('AC-002: HTTP sum computes values and rejects invalid input', async t => {
+  const server = createApplication();
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  t.after(() => new Promise(resolve => server.close(resolve)));
+  const url = `http://127.0.0.1:${server.address().port}/sum`;
+  const response = await fetch(url, { method: 'POST', body: JSON.stringify({ left: 2, right: 3 }) });
+  assert.equal(response.status, 200);
+  assert.deepEqual(await response.json(), { result: 5 });
+  const invalid = await fetch(url, { method: 'POST', body: JSON.stringify({ left: '2', right: 3 }) });
+  assert.equal(invalid.status, 400);
+  assert.deepEqual(await invalid.json(), { error: 'invalid input' });
+});

package/.pbai4devs/scripts/testar-maturidade/assets/server.mjs

@@ -0,0 +1,34 @@
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+
+const add = (left, right) => left + right;
+
+export function createApplication() {
+  return createServer(async (request, response) => {
+    response.setHeader('content-type', 'application/json');
+    if (request.method === 'GET' && request.url === '/health') {
+      response.end(JSON.stringify({ status: 'ok' }));
+      return;
+    }
+    if (request.method === 'POST' && request.url === '/sum') {
+      try {
+        let body = '';
+        for await (const chunk of request) body += chunk;
+        const { left, right } = JSON.parse(body);
+        if (!Number.isFinite(left) || !Number.isFinite(right)) throw new Error('invalid numbers');
+        response.end(JSON.stringify({ result: add(left, right) }));
+      } catch {
+        response.statusCode = 400;
+        response.end(JSON.stringify({ error: 'invalid input' }));
+      }
+      return;
+    }
+    response.statusCode = 404;
+    response.end(JSON.stringify({ error: 'not found' }));
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const server = createApplication();
+  server.listen(Number(process.env.PORT || 3000), '0.0.0.0');
+}

package/.pbai4devs/scripts/testar-maturidade/tests/TEST.mjs

@@ -0,0 +1,305 @@
+import assert from 'node:assert/strict';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import test from 'node:test';
+import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+import { copyAgentStructure, prepareExamples as prepare, registeredRoots, resourceTargets, SCENARIOS } from '../SCRIPT.mjs';
+
+// As fixtures pequenas isolam a cópia; o caso source-only usa o renderizador real.
+const prepareExamples = options => prepare({ ...options, renderResources: () => {} });
+
+requireNode();
+function fixture(t) {
+  const home = join(projectRoot, '.agent-tests'); mkdirSync(home, { recursive: true });
+  const root = mkdtempSync(join(home, 'maturity-unit-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const put = (name, content = '') => { const file = join(root, name); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, content); return file; };
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\nagente|.github|plano\nagente|.agents|plano\nagente|.agent|plano\nagente|.gemini|plano\ngitignore|.vscode\n');
+  put('.pbai4devs/skills.json', '{"entries":[{"path":".pbai4devs/skills/projeto/demo"}]}');
+  put('.pbai4devs/skills/projeto/demo/SKILL.md', '---\nname: demo\ndescription: Fixture.\n---\n\n# Demo\n');
+  put('.codex/skills/demo/SKILL.md', 'ponteiro'); put('.github/skills/demo/SKILL.md', 'ponteiro');
+  for (const client of ['.agents', '.agent', '.gemini']) put(`${client}/skills/demo/SKILL.md`, 'ponteiro');
+  put('.gemini/commands/demo.toml', 'description = "Fixture"\nprompt = "Leia o recurso compartilhado."\n');
+  put('.vscode/settings.json', '{"fixture":true}\n');
+  for (const name of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'README.md', '.gitattributes', '.editorconfig']) put(name, 'fixture\n');
+  put('.gitignore', readFileSync(join(projectRoot, '.gitignore')));
+  put('.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs', readFileSync(join(projectRoot, '.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs')));
+  put('.pbai4devs/scripts/lib/runtime.mjs', readFileSync(join(projectRoot, '.pbai4devs/scripts/lib/runtime.mjs')));
+  return { root, put, outputRoot: join(root, 'examples/generated') };
+}
+
+test('copia recursos e configurações, excluindo payloads, caches e segredos', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/tools/demo/TOOL.json', '{}'); put('.pbai4devs/tools/demo/SCRIPT.mjs', 'export {};'); put('.pbai4devs/tools/demo/README.md', '# Tool');
+  put('.pbai4devs/templates/demo/TEMPLATE.md', '# Template');
+  put('.pbai4devs/scripts/demo/tests/fixture.json', '{"keep":true}');
+  put('.pbai4devs/external-skills/README.md', '# External'); put('.pbai4devs/external-skills/CATALOG.json', '{}');
+  put('.env.example', 'PORT=3000\n');
+  const excluded = ['.pbai4devs/tools/demo/.local/package/README.md', '.pbai4devs/tools/demo/download.exe', '.pbai4devs/tools/.cache/archive', '.pbai4devs/tools/bin/demo.mjs', '.pbai4devs/external-skills/.local/upstream/SKILL.md', '.pbai4devs/scripts/demo/node_modules/pkg/index.js', '.pbai4devs/scripts/demo/.env', '.pbai4devs/scripts/demo/report.log', '.env', '.codex/auth.json', '.github/credentials.json', '.vscode/settings.local.json', '.pbai4devs/scripts/demo/private.pem', '.pbai4devs/scripts/demo/config.local.toml', '.codex/.credentials.json', '.agents/.local/token.json', '.gemini/auth.json'];
+  excluded.push('.pbai4devs/scripts/demo/playwright-report/index.html', '.pbai4devs/scripts/demo/TEST-RESULTS/report.json', '.pbai4devs/scripts/demo/TmP/generated.json', '.gemini/Temp/context.json', '.gemini/Sessions/state.json', '.pbai4devs/scripts/demo/history.jsonl', '.pbai4devs/skills/demo/.PLAYWRIGHT-MCP/session.json');
+  excluded.push('.pbai4devs/bin/agentdevkit.mjs', '.pbai4devs/src/cli.mjs', '.pbai4devs/release/pipeline.mjs', '.pbai4devs/tests/cli.test.mjs', '.pbai4devs/DEVELOPMENT.md');
+  excluded.push('bin/agentdevkit.mjs', 'src/cli.mjs', 'scripts/release/pipeline.mjs', 'tests/cli.test.mjs', 'examples/README.md');
+  const kept = ['.pbai4devs/scripts/demo/tests/fixtures/cache/input.json', '.pbai4devs/scripts/demo/tests/fixtures/playwright-response.json', '.pbai4devs/templates/demo/compose.local.yml.template'];
+  for (const file of kept) put(file, 'fixture versionavel');
+  for (const file of excluded) put(file, 'não copiar');
+  const destination = join(root, 'copy');
+  const result = copyAgentStructure(root, destination);
+  assert.ok(result.copiedFiles > 10);
+  for (const file of excluded) assert.equal(existsSync(join(destination, file)), false, file);
+  for (const file of excluded) assert.equal(readFileSync(join(root, file), 'utf8'), 'não copiar', `Origem alterada: ${file}`);
+  for (const file of ['.pbai4devs/tools/demo/TOOL.json', '.pbai4devs/tools/demo/SCRIPT.mjs', '.pbai4devs/external-skills/CATALOG.json', '.pbai4devs/templates/demo/TEMPLATE.md', '.pbai4devs/scripts/demo/tests/fixture.json', '.vscode/settings.json', '.gitattributes', '.env.example', '.agents/skills/demo/SKILL.md', '.agent/skills/demo/SKILL.md', '.gemini/skills/demo/SKILL.md', '.gemini/commands/demo.toml', 'GEMINI.md']) assert.ok(existsSync(join(destination, file)), file);
+  for (const file of kept) assert.equal(readFileSync(join(destination, file), 'utf8'), 'fixture versionavel');
+  assert.deepEqual(result.roots, ['.pbai4devs', '.codex', '.github', '.agents', '.agent', '.gemini', '.vscode']);
+});
+
+test('regeneração preserva pastas alheias e recusa sobrescrevê-las', t => {
+  const { root, put, outputRoot } = fixture(t);
+  put('examples/generated/anotacoes/keep.txt', 'preservado');
+  put('examples/README.md', 'Guia humano.');
+  const options = { sourceRoot: root, outputRoot, scenarios: [SCENARIOS[0]], initializeGit: false };
+  prepareExamples(options); prepareExamples(options);
+  assert.equal(readFileSync(join(outputRoot, 'anotacoes/keep.txt'), 'utf8'), 'preservado');
+  assert.equal(readFileSync(join(root, 'examples/README.md'), 'utf8'), 'Guia humano.');
+  put('examples/generated/descoberta/keep.txt', 'humano');
+  assert.throws(() => prepareExamples({ ...options, scenarios: [SCENARIOS[1]] }), /não é gerenciado/);
+  assert.equal(readFileSync(join(outputRoot, 'descoberta/keep.txt'), 'utf8'), 'humano');
+  assert.throws(() => prepareExamples({ ...options, scenarios: [{ ...SCENARIOS[0], id: '../outside' }] }), /IDs únicos e seguros/);
+});
+
+test('destino padrão redefine apenas relatório próprio e mantém resultados fora do Git', t => {
+  const { root, outputRoot } = fixture(t);
+  const git = (...args) => {
+    const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', shell: false });
+    assert.ifError(result.error); assert.equal(result.status, 0, result.stderr); return result.stdout;
+  };
+  git('init', '--template=', '--quiet');
+  const options = { sourceRoot: root, scenarios: [SCENARIOS[0]], initializeGit: false };
+  const examples = prepareExamples(options);
+  assert.equal(examples[0].root, join(outputRoot, SCENARIOS[0].id));
+  const reportFile = join(outputRoot, 'REPORT.json');
+  writeFileSync(reportFile, JSON.stringify({ owner: 'testar-maturidade', status: 'passed', results: [{ stale: true }] }));
+  prepareExamples(options);
+  assert.deepEqual(JSON.parse(readFileSync(reportFile)), { owner: 'testar-maturidade', version: 1,
+    status: 'prepared', scenarios: [SCENARIOS[0].id], results: [] });
+  assert.match(git('check-ignore', '--verbose', 'examples/generated/REPORT.json'), /examples\/generated\/\.gitignore:2:\*/);
+  assert.match(git('check-ignore', '--verbose', 'examples/generated/somente-agentes/README.md'), /examples\/generated\/\.gitignore:2:\*/);
+  const human = JSON.stringify({ owner: 'human', notes: 'preservar' });
+  writeFileSync(reportFile, human);
+  assert.throws(() => prepareExamples(options), /Relatório.*não pertence/);
+  assert.equal(readFileSync(reportFile, 'utf8'), human);
+});
+
+test('preserva ignore humano e continua aceitando destinos legados', t => {
+  const { root, put } = fixture(t);
+  const options = { sourceRoot: root, scenarios: [SCENARIOS[0]], initializeGit: false };
+  put('examples/generated/.gitignore', '!README.md\n');
+  assert.throws(() => prepareExamples(options), /Ignore.*não pertence/);
+  assert.equal(readFileSync(join(root, 'examples/generated/.gitignore'), 'utf8'), '!README.md\n');
+  for (const target of ['tmp/examples', '.agent-tests/cases']) {
+    const outputRoot = join(root, target);
+    const [example] = prepareExamples({ ...options, outputRoot });
+    assert.equal(example.root, join(outputRoot, SCENARIOS[0].id));
+  }
+});
+
+test('preparação interrompida não conserva resultado anterior nem declara sucesso', t => {
+  const { root, put, outputRoot } = fixture(t);
+  const options = { sourceRoot: root, scenarios: [SCENARIOS[0]], initializeGit: false };
+  prepareExamples(options);
+  const report = join(outputRoot, 'REPORT.json');
+  const index = join(outputRoot, 'README.md');
+  writeFileSync(report, JSON.stringify({ owner: 'testar-maturidade', status: 'passed', results: [{}] }));
+  writeFileSync(index, readFileSync(index, 'utf8').replaceAll('prepared', 'passed'));
+  put('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ blocks: null }));
+  assert.throws(() => prepareExamples(options), /Estado da instalação/);
+  assert.equal(existsSync(report), false);
+  assert.match(readFileSync(index, 'utf8'), /status: preparing/);
+  assert.doesNotMatch(readFileSync(index, 'utf8'), /status: passed|\| passed \|/);
+  assert.doesNotMatch(readFileSync(index, 'utf8'), /\n{3,}/);
+});
+
+test('usa entradas distribuídas do hub e mantém fallback legado', t => {
+  const { root, put } = fixture(t);
+  const template = '---\ndescription: Entrada genérica.\n---\n\n# Agentes do projeto\n';
+  put('AGENTS.md', '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
+  put('.pbai4devs/templates/entrypoints/AGENTS.md', template);
+  const destination = join(root, 'copy');
+  const copied = copyAgentStructure(root, destination);
+  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), template);
+  assert.equal(readFileSync(join(destination, 'CLAUDE.md'), 'utf8'), 'fixture\n');
+  assert.equal(copied.entrypoints['AGENTS.md'], '.pbai4devs/templates/entrypoints/AGENTS.md');
+  assert.equal(copied.entrypoints['CLAUDE.md'], 'CLAUDE.md');
+  assert.equal(readFileSync(join(root, 'AGENTS.md'), 'utf8'), '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
+});
+
+test('cópias respeitam clientes e entradas de instalações parciais', async t => {
+  for (const [client, manifest, entrypoints] of [
+    ['claude', 'agente|.claude|plano\n', ['AGENTS.md', 'CLAUDE.md']],
+    ['codex', 'agente|.codex|agrupado\nagente|.agents|agrupado\n', ['AGENTS.md']],
+  ]) await t.test(client, t => {
+    const { root, put } = fixture(t);
+    put('.pbai4devs/espelhos.conf', manifest);
+    put('.claude/skills/demo/SKILL.md', 'ponteiro');
+    for (const name of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
+      put(`.pbai4devs/templates/entrypoints/${name}`, `# Modelo ${name}\n`);
+      if (!entrypoints.includes(name)) rmSync(join(root, name));
+    }
+    const destination = join(root, 'copy');
+    const copied = copyAgentStructure(root, destination);
+    assert.deepEqual(Object.keys(copied.entrypoints), entrypoints);
+    for (const name of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
+      assert.equal(existsSync(join(destination, name)), entrypoints.includes(name), name);
+      assert.ok(existsSync(join(destination, '.pbai4devs/templates/entrypoints', name)));
+    }
+    assert.equal(existsSync(join(destination, '.vscode')), false);
+    assert.equal(existsSync(join(root, '.vscode/settings.json')), true);
+    assert.equal(existsSync(join(destination, '.github')), false);
+    assert.equal(existsSync(join(destination, '.gemini')), false);
+    if (client === 'claude') {
+      assert.deepEqual(copied.roots, ['.pbai4devs', '.claude']);
+      assert.equal(existsSync(join(destination, '.codex')), false);
+      assert.equal(existsSync(join(destination, '.agents')), false);
+    } else {
+      assert.deepEqual(copied.roots, ['.pbai4devs', '.codex', '.agents']);
+      assert.equal(existsSync(join(destination, '.claude')), false);
+    }
+  });
+});
+
+test('configurações do editor exigem registro explícito no manifesto', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\nagente|.vscode|plano\ngitignore|.vscode\n');
+  const destination = join(root, 'copy');
+  const copied = copyAgentStructure(root, destination);
+  assert.deepEqual(copied.roots, ['.pbai4devs', '.codex', '.vscode']);
+  assert.equal(readFileSync(join(destination, '.vscode/settings.json'), 'utf8'), '{"fixture":true}\n');
+});
+
+test('instalação parcial preserva entradas próprias e blocos editados', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|agrupado\nagente|.agents|agrupado\n');
+  const block = '<!-- BEGIN AGENTDEVKIT -->\nEntrada gerenciada.\n<!-- END AGENTDEVKIT -->';
+  put('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, version: '1.0.0', language: 'pt', clients: ['codex'], files: {}, blocks: { 'AGENTS.md': createHash('sha256').update(block).digest('hex') } }));
+  put('AGENTS.md', `# Agentes\n\n${block}\n`);
+  const human = '# Claude pessoal\r\n\r\nPreservar byte a byte: ação.\r\n';
+  put('CLAUDE.md', human);
+  rmSync(join(root, 'GEMINI.md'));
+  for (const name of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) put(`.pbai4devs/templates/entrypoints/${name}`, `# Modelo ${name}\n`);
+  const destination = join(root, 'copy');
+  const copied = copyAgentStructure(root, destination);
+  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), '# Modelo AGENTS.md\n');
+  assert.deepEqual(readFileSync(join(destination, 'CLAUDE.md')), Buffer.from(human));
+  assert.doesNotMatch(readFileSync(join(destination, 'CLAUDE.md'), 'utf8'), /BEGIN AGENTDEVKIT/);
+  assert.equal(copied.entrypoints['AGENTS.md'], '.pbai4devs/templates/entrypoints/AGENTS.md');
+  assert.equal(copied.entrypoints['CLAUDE.md'], 'CLAUDE.md');
+  assert.equal(existsSync(join(destination, 'GEMINI.md')), false);
+  assert.equal(existsSync(join(destination, '.claude')), false);
+  assert.equal(existsSync(join(destination, '.vscode')), false);
+  put('AGENTS.md', `# Agentes\n\n${block.replace('gerenciada', 'editada')}\n`);
+  const changed = join(root, 'changed-copy');
+  copyAgentStructure(root, changed);
+  assert.deepEqual(readFileSync(join(changed, 'AGENTS.md')), readFileSync(join(root, 'AGENTS.md')));
+});
+
+test('localiza apontamentos pelo formato de cada tipo e por overrides nativos', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', [
+    'agente|.claude|agrupado', 'formato|.claude|skills|plano',
+    'agente|.codex|plano', 'formato|.codex|skills|agrupado',
+    'nativo|.codex/skills/alias/SKILL.md|.pbai4devs/skills/projeto/demo/SKILL.md',
+  ].join('\n') + '\n');
+  assert.deepEqual(resourceTargets(root, '.pbai4devs/skills/projeto/demo/SKILL.md'), [
+    '.claude/skills/demo/SKILL.md', '.codex/skills/projeto/demo/SKILL.md', '.codex/skills/alias/SKILL.md',
+  ]);
+});
+
+test('checkout de fontes sem manifesto deriva clientes em memória', t => {
+  const { root, put } = fixture(t);
+  const manifest = join(root, '.pbai4devs/espelhos.conf');
+  rmSync(manifest);
+  assert.ok(registeredRoots(root).includes('.claude'));
+  const source = '.pbai4devs/skills/projeto/demo/SKILL.md';
+  assert.ok(resourceTargets(root, source).includes('.claude/skills/demo/SKILL.md'));
+  put('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ clients: ['claude'] }));
+  assert.deepEqual(registeredRoots(root), ['.claude']);
+  assert.deepEqual(resourceTargets(root, source), ['.claude/skills/demo/SKILL.md']);
+  assert.equal(existsSync(manifest), false);
+});
+
+test('prepare gera apontamentos reais mesmo sem pastas de clientes na origem', t => {
+  const { root } = fixture(t);
+  const sourceRoot = join(root, 'source-only');
+  copyAgentStructure(projectRoot, sourceRoot);
+  const roots = registeredRoots(sourceRoot);
+  for (const client of roots) rmSync(join(sourceRoot, client), { recursive: true, force: true });
+  const [example] = prepare({ sourceRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
+  const skill = '.pbai4devs/skills/projeto/criar-skill/SKILL.md';
+  for (const target of resourceTargets(sourceRoot, skill)) assert.ok(existsSync(join(example.root, target)), target);
+  for (const client of roots) assert.equal(existsSync(join(sourceRoot, client)), false, client);
+  for (const file of ['src/cli.mjs', 'bin/agentdevkit.mjs', 'scripts/release/pipeline.mjs', 'tests/cli.test.mjs']) assert.equal(existsSync(join(example.root, file)), false, file);
+});
+
+test('saída não pode sobrepor recursos de origem nem escapar das áreas de teste', t => {
+  const { root } = fixture(t);
+  const original = readFileSync(join(root, '.pbai4devs/espelhos.conf'), 'utf8');
+  for (const location of ['.pbai4devs/generated', '.github', '.codex', '.agents', '.agent', '.gemini', 'examples', 'examples/custom', 'tmp', 'output', '../outside']) {
+    assert.throws(() => prepareExamples({ sourceRoot: root, outputRoot: join(root, location), scenarios: [SCENARIOS[0]], initializeGit: false }), /Saída permitida/);
+    assert.equal(readFileSync(join(root, '.pbai4devs/espelhos.conf'), 'utf8'), original);
+    assert.equal(existsSync(join(root, location, '.maturity-suite.json')), false);
+  }
+  const outputRoot = join(root, '.agent-tests/permitted');
+  const examples = prepareExamples({ sourceRoot: root, outputRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
+  assert.equal(examples.length, 1);
+  assert.equal(readFileSync(join(root, '.pbai4devs/espelhos.conf'), 'utf8'), original);
+});
+
+test('oito cópias exercitam os seis níveis e preservam layouts legado/monorepo', t => {
+  const { root, outputRoot } = fixture(t);
+  const examples = prepareExamples({ sourceRoot: root, outputRoot, initializeGit: false });
+  assert.equal(examples.length, 8);
+  for (const example of examples) {
+    assert.doesNotMatch(readFileSync(join(example.root, 'README.md'), 'utf8'), /\n{3,}/);
+    const result = spawnSync(process.execPath, ['.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs'], { cwd: example.root, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    const report = JSON.parse(result.stdout);
+    assert.equal(report.maturity.level, example.expected, example.id);
+    assert.equal(report.contract.complete, example.complete, example.id);
+  }
+  const legacy = examples.find(example => example.id === 'legado');
+  assert.ok(existsSync(join(legacy.root, 'legacy/server.mjs')));
+  assert.match(readFileSync(join(legacy.root, 'package.json'), 'utf8'), /dev:old/);
+  const monorepo = examples.find(example => example.id === 'monorepo');
+  assert.ok(existsSync(join(monorepo.root, 'apps/painel com espaços/package.json')));
+  assert.ok(existsSync(join(monorepo.root, 'packages/cálculo/package.json')));
+  assert.equal(existsSync(join(monorepo.root, 'src')), false);
+});
+
+test('fixtures padrão, legado e monorepo executam HTTP real e encerram', t => {
+  const { root, outputRoot } = fixture(t);
+  const scenarios = SCENARIOS.filter(example => ['app-inicial', 'legado', 'monorepo'].includes(example.id));
+  const examples = prepareExamples({ sourceRoot: root, outputRoot, scenarios, initializeGit: false });
+  for (const example of examples) {
+    const environment = { ...process.env }; delete environment.NODE_TEST_CONTEXT;
+    const result = spawnSync(process.execPath, ['--test', ...example.application.tests], { cwd: example.root, env: environment, encoding: 'utf8', timeout: 30000 });
+    assert.ifError(result.error); assert.equal(result.status, 0, result.stderr || result.stdout);
+    assert.match(result.stdout, /AC-001/); assert.match(result.stdout, /AC-002/);
+    if (example.id === 'monorepo') assert.match(result.stdout, /AC-003/);
+  }
+});
+
+test('recusa links de origem e de saída, inclusive quebrados', t => {
+  const { root, put, outputRoot } = fixture(t);
+  const target = put('payload.txt', 'fora da cópia');
+  const link = join(root, '.pbai4devs/scripts/alias.mjs');
+  try { symlinkSync(target, link); }
+  catch (error) { if (process.platform === 'win32' && ['EPERM', 'EACCES'].includes(error.code)) { t.skip('Sem permissão para criar symlink de arquivo.'); return; } throw error; }
+  assert.throws(() => copyAgentStructure(root, join(root, 'copy')), /recusa links/);
+  rmSync(link); symlinkSync(join(root, 'missing.mjs'), link);
+  assert.throws(() => copyAgentStructure(root, join(root, 'copy')), /recusa links/);
+  rmSync(link);
+  mkdirSync(dirname(outputRoot), { recursive: true });
+  symlinkSync(join(root, 'missing-output'), outputRoot, process.platform === 'win32' ? 'junction' : 'dir');
+  assert.throws(() => prepareExamples({ sourceRoot: root, outputRoot, scenarios: [SCENARIOS[0]], initializeGit: false }), /não pode ser link/);
+});

package/.pbai4devs/scripts/testar-navegador/REFERENCE.md

@@ -0,0 +1,49 @@
+---
+description: Execução de cenários reutilizáveis no conector Playwright.
+---
+
+# Testar no navegador
+
+Use quando o agente tiver `browser_run_code_unsafe` com `code` e `filename`.
+O script usa a página do conector, não requer instalar Playwright no projeto.
+Se a ferramenta não existir ou não compartilhar a página entre chamadas,
+use os testes Playwright do projeto ou informe a limitação.
+
+1. Abra a URL real e observe os controles pelo snapshot da ferramenta.
+2. Em `browser_run_code_unsafe`, passe uma função como esta em `code`, com os
+   controles e resultados observados; não coloque credenciais no cenário.
+
+   ```js
+   async (page) => {
+     page.__agentsRequest = {
+       url: 'http://localhost:3000',
+       steps: [{ action: 'visible', role: 'heading', name: 'Título real' }]
+     };
+     return { ready: true };
+   }
+   ```
+
+3. Execute `filename: '.pbai4devs/scripts/testar-navegador/SCRIPT.js'` na mesma
+   ferramenta. Confira `passed`, cada viewport e os erros; salve o resultado
+   em `.agent-tests/<tarefa>/resultado.json`.
+4. Capture a tela com a ferramenta em `.agent-tests/<tarefa>/tela.png` e
+   inspecione-a. Encerre somente a página ou sessão aberta para esta tarefa.
+
+Por padrão, são usados 1280×800 e 390×844. O cenário aceita `viewports`,
+`timeout` (máximo 30 segundos) e `title`. Cada passo usa `testId`, `label` ou
+`role` e `name` exatos, com uma das ações:
+
+| Ação | Dados |
+| --- | --- |
+| `visible`, `click` | Controle observado |
+| `text`, `fill`, `select` | `value` |
+| `press` | `key` |
+| `check` | `checked` (padrão: `true`) |
+
+É obrigatória uma asserção `visible` ou `text`. Console, página e rede com
+erros reprovam o cenário; investigue a origem sem suprimir falhas para aprovar.
+Fluxos destrutivos exigem dados e ambiente de teste apropriados, com limpeza.
+
+Para provar só a infraestrutura, execute `tests/SUCCESS.js` desta pasta
+e depois o executor; espere `passed: true`. Repita com `tests/FAIL.js`; espere
+`passed: false` por erro de console. Essas fixtures não verificam o produto.

package/.pbai4devs/scripts/testar-navegador/SCRIPT.conf

@@ -0,0 +1 @@
+executor=playwright-mcp

package/.pbai4devs/scripts/testar-navegador/SCRIPT.js

@@ -0,0 +1,64 @@
+async (page) => {
+  const request = page.__agentsRequest;
+  delete page.__agentsRequest;
+  if (!request || (!request.url && !request.fixtureHtml)) throw new Error('Defina page.__agentsRequest com URL ou fixtureHtml.');
+  if (!request.steps?.some(step => ['visible', 'text'].includes(step.action))) throw new Error('Informe ao menos uma verificacao observavel.');
+  const viewports = request.viewports || [{ width: 1280, height: 800 }, { width: 390, height: 844 }];
+  if (!viewports.length || viewports.some(size => !(size.width > 0 && size.height > 0))) throw new Error('Viewports invalidos.');
+  const errors = [];
+  const cleanUrl = value => { try { const url = new URL(value); return url.origin === 'null' ? url.protocol + url.pathname : url.origin + url.pathname; } catch { return value; } };
+  const onConsole = message => { if (message.type() === 'error') errors.push({ type: 'console', message: message.text().slice(0, 300) }); };
+  const onPage = error => errors.push({ type: 'page', message: error.message.slice(0, 300) });
+  const onRequest = req => errors.push({ type: 'network', url: cleanUrl(req.url()), message: req.failure()?.errorText });
+  const onResponse = response => { if (response.status() >= 400) errors.push({ type: 'http', status: response.status(), url: cleanUrl(response.url()) }); };
+  const locate = step => {
+    if (step.testId) return page.getByTestId(step.testId);
+    if (step.role && step.name) return page.getByRole(step.role, { name: step.name, exact: true });
+    if (step.label) return page.getByLabel(step.label, { exact: true });
+    throw new Error('Informe role/name, label ou testId observado na interface.');
+  };
+  const results = [];
+  page.setDefaultTimeout(Math.min(request.timeout || 10000, 30000));
+  page.on('console', onConsole); page.on('pageerror', onPage);
+  page.on('requestfailed', onRequest); page.on('response', onResponse);
+  try {
+    for (const viewport of viewports) {
+      errors.length = 0;
+      const result = { viewport, passed: false, steps: 0 };
+      try {
+        await page.setViewportSize(viewport);
+        if (request.fixtureHtml) await page.setContent(request.fixtureHtml, { waitUntil: 'domcontentloaded' });
+        else {
+          const response = await page.goto(request.url, { waitUntil: 'domcontentloaded' });
+          if (!response || !response.ok()) throw new Error(`Navegacao falhou: ${response?.status()}`);
+        }
+        if (request.title && await page.title() !== request.title) throw new Error('Titulo divergente.');
+        for (const step of request.steps || []) {
+          const locator = locate(step);
+          switch (step.action) {
+            case 'fill': await locator.fill(step.value); break;
+            case 'click': await locator.click(); break;
+            case 'press': await locator.press(step.key); break;
+            case 'select': await locator.selectOption(step.value); break;
+            case 'check': await locator.setChecked(step.checked !== false); break;
+            case 'visible': await locator.waitFor({ state: 'visible' }); break;
+            case 'text':
+              const escaped = step.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+              await locator.filter({ hasText: new RegExp(`^\\s*${escaped}\\s*$`) }).waitFor({ state: 'visible' });
+              if ((await locator.innerText()).trim() !== step.value) throw new Error('Texto divergente.');
+              break;
+            default: throw new Error(`Acao desconhecida: ${step.action}`);
+          }
+          result.steps++;
+        }
+        if (errors.length) throw new Error('Erros de console, pagina ou rede.');
+        result.passed = true;
+      } catch (error) { result.failure = error.message.slice(0, 300); }
+      result.errors = [...errors]; results.push(result);
+    }
+  } finally {
+    page.off('console', onConsole); page.off('pageerror', onPage);
+    page.off('requestfailed', onRequest); page.off('response', onResponse);
+  }
+  return { mode: request.fixtureHtml ? 'fixture' : 'application', passed: results.every(x => x.passed), browser: page.context().browser()?.browserType().name(), version: page.context().browser()?.version(), url: cleanUrl(page.url()), results };
+}

package/.pbai4devs/scripts/testar-navegador/tests/FAIL.js

@@ -0,0 +1,8 @@
+async (page) => {
+  page.__agentsRequest = {
+    fixtureHtml: '<!doctype html><html><body><h1>Falha esperada</h1><script>console.error("erro de prova")</script></body></html>',
+    viewports: [{ width: 1280, height: 800 }],
+    steps: [{ action: 'visible', role: 'heading', name: 'Falha esperada' }]
+  };
+  return { fixture: 'failure-ready', expected: 'passed=false', next: '.pbai4devs/scripts/testar-navegador/SCRIPT.js' };
+}

package/.pbai4devs/scripts/testar-navegador/tests/SUCCESS.js

@@ -0,0 +1,13 @@
+async (page) => {
+  page.__agentsRequest = {
+    fixtureHtml: '<!doctype html><html lang="pt-BR"><head><meta name="viewport" content="width=device-width,initial-scale=1"><title>Prova dos agentes</title></head><body><main><h1>Prova dos agentes</h1><form><label>Nome<input name="nome" required></label><button type="submit">Confirmar</button></form><p role="status" data-testid="resultado"></p></main><script>document.querySelector("form").onsubmit=e=>{e.preventDefault();document.querySelector("[role=status]").textContent="Ola, "+e.target.nome.value}</script></body></html>',
+    title: 'Prova dos agentes',
+    steps: [
+      { action: 'visible', role: 'heading', name: 'Prova dos agentes' },
+      { action: 'fill', label: 'Nome', value: 'Agente' },
+      { action: 'click', role: 'button', name: 'Confirmar' },
+      { action: 'text', testId: 'resultado', value: 'Ola, Agente' }
+    ]
+  };
+  return { fixture: 'ready', next: '.pbai4devs/scripts/testar-navegador/SCRIPT.js' };
+}

package/.pbai4devs/scripts/verificar-recursos/README.md

@@ -0,0 +1,25 @@
+---
+description: Verificação dos recursos compartilhados e de seus apontamentos.
+---
+
+# Verificar recursos
+
+```sh
+node .pbai4devs/scripts/verificar-recursos/SCRIPT.mjs
+node .pbai4devs/scripts/verificar-recursos/SCRIPT.mjs --source-only
+node --test .pbai4devs/scripts/verificar-recursos/tests/TEST.mjs
+```
+
+Exige Node 24+. Confere espelhos, frontmatter/H1, links locais e guias das
+ferramentas. Ignora pacotes baixados e resultados temporários, inclusive
+Playwright em qualquer caixa. Fixtures comuns continuam verificadas.
+Inclui Markdown da raiz, de `docs/`, `src/`, `bin/`, `tests/`, `scripts/`,
+`examples/` e templates de contribuição do GitHub. Exclui `examples/generated/`.
+Essa coleta usa somente o diretório informado, sem buscar outro repositório Git.
+Usa o Markdown lint local
+quando instalado e informa sua ausência. Não instala nem sincroniza recursos.
+Testes e fixtures são versionados; temporários ficam em `.agent-tests/`.
+
+`--source-only` valida as fontes sem exigir catálogos, manifesto ou clientes
+gerados. Referências aos índices derivados são conferidas pelo catálogo em
+memória; links para fontes inexistentes continuam sendo erros.