@pathbit/agentdevkit 0.0.0-stage → 0.0.5

package/.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// Inventario somente leitura; nomes e caminhos, nunca valores de configuracao.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { requireNode, isMain } from '../lib/runtime.mjs';
+
+const repository = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..'));
+const defaultAgents = ['.agents', '.agent', '.gemini', '.claude', '.codex', '.cursor', '.github', '.opencode'];
+const defaultExcluded = ['.git', '.pbai4devs', '.agent-tests', ...defaultAgents, '.vscode', 'node_modules', 'vendor', 'target', 'dist', 'build', 'bin', 'obj', '.venv', 'venv', '.cache', '.next', '.nuxt', 'coverage', 'test-results', 'playwright-report', 'blob-report', 'tmp', 'temp', 'examples'];
+const manifests = new Map([
+  ['package.json', 'javascript'], ['deno.json', 'javascript'], ['deno.jsonc', 'javascript'],
+  ['pyproject.toml', 'python'], ['Pipfile', 'python'], ['setup.py', 'python'], ['setup.cfg', 'python'],
+  ['Cargo.toml', 'rust'], ['go.mod', 'go'], ['pom.xml', 'java'], ['build.gradle', 'java'], ['build.gradle.kts', 'kotlin'],
+  ['composer.json', 'php'], ['Gemfile', 'ruby'], ['mix.exs', 'elixir'], ['pubspec.yaml', 'dart'],
+  ['Package.swift', 'swift'], ['CMakeLists.txt', 'cpp']
+]);
+const locks = new Set(['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb', 'deno.lock', 'uv.lock', 'poetry.lock', 'Pipfile.lock', 'Cargo.lock', 'go.sum', 'composer.lock', 'Gemfile.lock', 'mix.lock', 'pubspec.lock', 'Package.resolved', 'packages.lock.json', 'gradle.lockfile']);
+const requiredDirectories = ['.pbai4devs', '.vscode', 'src', 'tests', 'infra'];
+function agentRoots(root) {
+  const file = path.join(root, '.pbai4devs/espelhos.conf');
+  if (!present(root, '.pbai4devs/espelhos.conf', false)) return defaultAgents;
+  const values = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(line => line.startsWith('agente|')).map(line => line.split('|')[1]);
+  const roots = [...new Set(values.filter(value => /^\.[a-z0-9][a-z0-9.-]*$/.test(value) && !['.git', '.pbai4devs', '.agent-tests'].includes(value)))];
+  return roots.length ? roots : defaultAgents;
+}
+const requiredFiles = ['.gitignore', '.gitattributes', '.editorconfig', '.dockerignore', 'Makefile', 'README.md'];
+const localCompose = ['infra/compose/compose.local.yml', 'infra/compose/docker-compose.local.yml'];
+const normalize = value => value.split(path.sep).join('/');
+const commandName = value => /^[A-Za-z0-9_][A-Za-z0-9_:./-]{0,99}$/.test(value);
+const present = (root, name, directory) => {
+  try {
+    let current = root; let item;
+    for (const part of name.split('/')) { current = path.join(current, part); item = fs.lstatSync(current); if (item.isSymbolicLink()) return false; }
+    return directory ? item.isDirectory() : item.isFile();
+  }
+  catch { return false; }
+};
+const inside = candidate => { const relative = path.relative(repository, candidate); return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative); };
+const fixturePath = candidate => /^(?:\.agent-tests\/|tmp\/examples\/|examples\/generated\/)/.test(normalize(path.relative(repository, candidate)));
+
+function metadata(root, file) {
+  if (!present(root, file, false) || fs.statSync(path.join(root, file)).size > 1024 * 1024) return { fields: {}, documents: {} };
+  const text = fs.readFileSync(path.join(root, file), 'utf8').replaceAll('\r', '');
+  const header = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
+  const result = { fields: {}, documents: {} }; if (!header) return result;
+  let documents = false;
+  const scalar = raw => {
+    const value = raw.trim();
+    if (!value || ['null', '~'].includes(value)) return null;
+    if (value.startsWith('"')) { try { return JSON.parse(value); } catch { return null; } }
+    return value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1).replaceAll("''", "'") : value;
+  };
+  for (const line of header.split('\n')) {
+    const top = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (top) { documents = top[1] === 'documentos'; result.fields[top[1]] = scalar(top[2]); }
+    else if (documents) { const item = line.match(/^  ([a-z_]+):\s*(.*)$/); if (item) result.documents[item[1]] = scalar(item[2]); }
+  }
+  return result;
+}
+
+function maturity(root, report) {
+  const stateFile = '.pbai4devs/estado/configuracao/ESTADO.md'; const state = metadata(root, stateFile);
+  const safeDocument = value => typeof value === 'string' && !path.isAbsolute(value) && !value.includes('\\') && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
+  const planning = {};
+  for (const name of ['prd', 'ux_ui', 'design']) {
+    const file = state.documents[name];
+    const exists = safeDocument(file) && /\.md$/i.test(file) && present(root, file, false);
+    const status = exists ? metadata(root, file).fields.status : null;
+    planning[name] = { path: safeDocument(file) ? file : null, present: Boolean(exists), status: ['rascunho', 'aprovado', 'nao-aplicavel', 'pendente'].includes(status) ? status : null };
+  }
+  planning.ready = planning.prd.status === 'aprovado' && planning.design.status === 'aprovado' && ['aprovado', 'nao-aplicavel'].includes(planning.ux_ui.status);
+  let released = false; const releases = state.documents.releases;
+  if (safeDocument(releases) && present(root, releases, true)) {
+    const visit = (directory, depth = 0) => {
+      for (const entry of fs.readdirSync(path.join(root, directory), { withFileTypes: true }).slice(0, 100)) {
+        const file = normalize(path.join(directory, entry.name));
+        if (entry.isSymbolicLink()) continue;
+        if (entry.isDirectory() && depth < 2) visit(file, depth + 1);
+        else if (entry.isFile() && /^RELEASE\.md$/i.test(entry.name) && ['publicado', 'concluido', 'released'].includes(metadata(root, file).fields.status)) released = true;
+      }
+    };
+    visit(releases);
+  }
+  const stateValue = value => ['pendente', 'concluido'].includes(value) ? value : null;
+  const configuration = { present: present(root, stateFile, false), preparacao: stateValue(state.fields.preparacao), configuracao_tecnica: stateValue(state.fields.configuracao_tecnica) };
+  let level = 'preparacao';
+  if (Object.values(planning).some(item => item && typeof item === 'object' && item.present)) level = 'descoberta';
+  if (planning.ready) level = 'planejado';
+  if (report.mode === 'aplicacao-detectada') level = 'implementacao';
+  if (report.mode === 'aplicacao-detectada' && planning.ready && report.contract.complete && configuration.configuracao_tecnica === 'concluido') level = released ? 'manutencao' : 'configurado';
+  return { level, planning, configuration, released, signals: { application: report.mode === 'aplicacao-detectada', structure: report.contract.complete }, limits: ['Classificacao descritiva; status em arquivos nao substitui aprovacao, testes ou provas de funcionamento.'] };
+}
+
+export function inspectProject(root = repository, { check = false } = {}) {
+  requireNode();
+  root = fs.realpathSync(path.resolve(root));
+  if (!fs.statSync(root).isDirectory()) throw new Error('A origem deve ser um diretorio.');
+  const excluded = new Set(defaultExcluded);
+  const configuredAgents = agentRoots(root); configuredAgents.forEach(name => excluded.add(name));
+  const report = { mode: 'agentes-sem-aplicacao', languages: [], manifests: [], lockfiles: [], commands: [], compose: [], dockerfiles: [], sources: [], structure: { present: [], missing: [] }, scan: { maxDepth: 6, truncated: false }, warnings: [] };
+  const languages = new Set(); let entries = 0;
+  const warning = (file, reason) => report.warnings.push({ file, reason });
+  function commands(file, name) {
+    if (!['package.json', 'composer.json', 'deno.json', 'deno.jsonc', 'Makefile', 'makefile', 'GNUmakefile', 'pyproject.toml'].includes(name)) return;
+    if (fs.statSync(path.join(root, file)).size > 1024 * 1024) { warning(file, 'manifest-grande-demais'); return; }
+    const text = fs.readFileSync(path.join(root, file), 'utf8');
+    let names = [];
+    try {
+      if (['package.json', 'composer.json', 'deno.json', 'deno.jsonc'].includes(name)) {
+        const data = JSON.parse(text);
+        names = Object.keys((name.startsWith('deno.') ? data.tasks : data.scripts) || {});
+      } else if (name === 'pyproject.toml') {
+        let section = false;
+        for (const line of text.split(/\r?\n/)) {
+          if (/^\s*\[/.test(line)) section = /^\s*\[(?:project\.scripts|tool\.poetry\.scripts)\]\s*(?:#.*)?$/.test(line);
+          else if (section) { const match = line.match(/^\s*([A-Za-z0-9_.-]+)\s*=/); if (match) names.push(match[1]); }
+        }
+      } else {
+        for (const line of text.split(/\r?\n/)) {
+          const match = line.match(/^([A-Za-z0-9_][A-Za-z0-9_ ./-]*)\s*:(?!=)/);
+          if (match) names.push(...match[1].trim().split(/\s+/));
+        }
+      }
+      names = [...new Set(names.filter(commandName))].sort();
+      if (names.length) report.commands.push({ file, names });
+    } catch { warning(file, 'manifest-nao-interpretado'); }
+  }
+  function walk(directory = '', depth = 0) {
+    const children = fs.readdirSync(path.join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const item of children) {
+      if (++entries > 25000) { report.scan.truncated = true; return; }
+      const file = normalize(path.join(directory, item.name));
+      if (/^\.playwright/i.test(item.name)) continue;
+      if (item.isSymbolicLink()) continue;
+      if (item.isDirectory()) {
+        if (excluded.has(item.name) || excluded.has(item.name.toLowerCase()) || /^\.?playwright/i.test(item.name)) continue;
+        if (depth < report.scan.maxDepth) walk(file, depth + 1); else report.scan.truncated = true;
+        continue;
+      }
+      if (!item.isFile()) continue;
+      let language = manifests.get(item.name);
+      if (/\.(?:csproj|fsproj|vbproj|sln)$/.test(item.name)) language = 'dotnet';
+      if (/^requirements(?:[.-][A-Za-z0-9_-]+)?\.txt$/.test(item.name)) language = 'python';
+      if (language) { report.manifests.push(file); languages.add(language); }
+      if (locks.has(item.name)) report.lockfiles.push(file);
+      if (/^(?:docker-)?compose(?:\.[A-Za-z0-9_-]+)*\.ya?ml$/i.test(item.name)) report.compose.push(file);
+      if (/^Dockerfile(?:\.[A-Za-z0-9_-]+)?$/.test(item.name) || /\.Dockerfile$/.test(item.name)) report.dockerfiles.push(file);
+      if (/\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|cs|fs|vb|php|rb|ex|exs|dart|swift|c|cpp|cc|h|hpp|vue|svelte)$/.test(item.name) && !/(^|\/)(?:tests?|spec|fixtures)(\/|$)|\.(?:test|spec)\./.test(file) && report.sources.length < 12) report.sources.push(file);
+      commands(file, item.name);
+    }
+  }
+  walk();
+  for (const [names, directory] of [[[...requiredDirectories, ...configuredAgents], true], [requiredFiles, false]]) {
+    for (const name of names) report.structure[present(root, name, directory) ? 'present' : 'missing'].push(name);
+  }
+  const compose = localCompose.find(name => present(root, name, false));
+  report.structure[compose ? 'present' : 'missing'].push(compose || localCompose[0]);
+  if (report.manifests.length || report.lockfiles.length || report.sources.length) report.mode = 'aplicacao-detectada';
+  report.languages = [...languages].sort();
+  report.contract = { checked: check, complete: report.structure.missing.length === 0 };
+  report.maturity = maturity(root, report);
+  return report;
+}
+
+export function main(args = process.argv.slice(2)) {
+  requireNode();
+  let root = repository; let check = false; args = [...args];
+  while (args.length) {
+    const option = args.shift();
+    if (option === '--check') check = true;
+    else if (option === '--root' && args.length) {
+      const candidate = path.resolve(repository, args.shift());
+      if (!inside(candidate) || !fixturePath(candidate)) throw new Error('--root aceita somente fixtures em examples/generated/, .agent-tests/ ou tmp/examples/ do repositorio ativo.');
+      root = fs.realpathSync(candidate);
+      if (!inside(root) || !fixturePath(root)) throw new Error('A fixture deve permanecer em examples/generated/, .agent-tests/ ou tmp/examples/ do repositorio ativo.');
+    } else throw new Error('Opcao invalida; use [--check] [--root <fixture-no-repositorio>].');
+  }
+  const report = inspectProject(root, { check });
+  console.log(JSON.stringify(report));
+  return check && !report.contract.complete ? 1 : 0;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = main(); }
+  catch (error) {
+    console.error(JSON.stringify({ error: error.code ? `Falha de leitura (${error.code}).` : error.message }));
+    process.exitCode = 2;
+  }
+}

package/.pbai4devs/scripts/inspecionar-projeto/tests/TEST.mjs

@@ -0,0 +1,161 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+
+requireNode();
+const script = join(projectRoot, '.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs');
+function fixture(t) {
+  const home = join(projectRoot, '.agent-tests');
+  mkdirSync(home, { recursive: true });
+  const root = mkdtempSync(join(home, 'inspecionar-projeto-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const directory = name => mkdirSync(join(root, name), { recursive: true });
+  const file = (name, data = '') => { const target = join(root, name); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, data); };
+  const run = (...args) => {
+    const result = spawnSync(process.execPath, [script, '--root', root, ...args], { encoding: 'utf8' });
+    assert.ifError(result.error);
+    return { ...result, report: result.stdout.trim() ? JSON.parse(result.stdout) : undefined };
+  };
+  return { root, directory, file, run };
+}
+
+test('identifica repositório sem aplicação e informa estrutura ausente', t => {
+  const { run } = fixture(t);
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.report.mode, 'agentes-sem-aplicacao');
+  assert.ok(result.report.structure.missing.includes('Makefile'));
+  assert.equal(run('--check').status, 1);
+});
+
+test('ignora agentes, dependências, estado e links simbólicos', t => {
+  const { root, file, run } = fixture(t);
+  file('.pbai4devs/tools/node_modules/example/package.json', '{"scripts":{"wrong":"secret"}}');
+  file('node_modules/example/package.json', '{}');
+  file('.git/package.json', '{}');
+  file('.agent-tests/package.json', '{}');
+  assert.equal(run().report.mode, 'agentes-sem-aplicacao');
+  try { symlinkSync(join(projectRoot, 'README.md'), join(root, 'linked.py')); }
+  catch (error) {
+    if (process.platform !== 'win32' || !['EPERM', 'EACCES'].includes(error.code)) throw error;
+    t.diagnostic('Link simbólico indisponível sem permissão do Windows.');
+  }
+  assert.equal(run().report.mode, 'agentes-sem-aplicacao');
+});
+
+test('descobre linguagens e comandos sem expor valores nem executar Python', t => {
+  const { root, file, run } = fixture(t);
+  const secret = 'THIS_VALUE_MUST_NEVER_APPEAR_393838';
+  file('.env', `TOKEN=${secret}`);
+  file('backend/pyproject.toml', `[project]\nname="existing"\n[project.scripts]\nserve="app:main"\n[tool.private]\npassword="${secret}"`);
+  file('backend/app.py', `password="${secret}"`);
+  file('deploy/docker-compose.dev.yml', `services:\n  app:\n    environment:\n      TOKEN: ${secret}\n`);
+  file('Dockerfile', `ENV TOKEN=${secret}`);
+  file('Makefile', `dev:\n\t@echo ${secret}\ntest check:\n\t@echo ok\n`);
+  file('package.json', JSON.stringify({ scripts: { dev: `echo ${secret}`, test: 'exit 0' }, config: { token: secret } }));
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.report.mode, 'aplicacao-detectada');
+  assert.deepEqual(result.report.languages, ['javascript', 'python']);
+  assert.ok(result.report.compose.includes('deploy/docker-compose.dev.yml'));
+  assert.ok(result.report.structure.missing.includes('src'));
+  assert.deepEqual(result.report.commands.find(row => row.file === 'package.json').names, ['dev', 'test']);
+  assert.deepEqual(result.report.commands.find(row => row.file === 'Makefile').names, ['check', 'dev', 'test']);
+  assert.deepEqual(result.report.commands.find(row => row.file === 'backend/pyproject.toml').names, ['serve']);
+  assert.ok(!result.stdout.includes(secret));
+  assert.ok(!result.stderr.includes(secret));
+  assert.equal(readFileSync(join(root, '.env'), 'utf8'), `TOKEN=${secret}`);
+});
+
+test('aceita estrutura completa e raízes de agentes configuradas', t => {
+  const { directory, file, run } = fixture(t);
+  for (const name of ['.pbai4devs', '.agents', '.agent', '.gemini', '.claude', '.codex', '.cursor', '.github', '.opencode', '.vscode', 'src', 'tests', 'infra']) directory(name);
+  for (const name of ['.gitignore', '.gitattributes', '.editorconfig', '.dockerignore', 'README.md', 'Makefile']) file(name);
+  file('infra/compose/docker-compose.local.yml', 'services: {}\n');
+  const result = run('--check');
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.report.contract.complete, true);
+  assert.deepEqual(result.report.structure.missing, []);
+  file('.pbai4devs/espelhos.conf', 'agente|.github|plano\nagente|.dsh|plano\n');
+  file('.dsh/skills/tool/package.json', '{"scripts":{"hidden":"secret"}}');
+  const configured = run('--check');
+  assert.equal(configured.status, 0, configured.stderr);
+  assert.ok(configured.report.structure.present.includes('.dsh'));
+  assert.ok(!configured.report.manifests.some(name => name.startsWith('.dsh/')));
+});
+
+test('manifests inválidos geram aviso sem revelar seu conteúdo', t => {
+  const { file, run } = fixture(t);
+  const secret = 'MALFORMED_PRIVATE_VALUE';
+  file('package.json', '{ malformed ' + secret);
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  assert.ok(result.report.warnings.some(row => row.file === 'package.json'));
+  assert.ok(!result.stdout.includes(secret));
+});
+
+test('rejeita origens fora das fixtures e opções desconhecidas', () => {
+  for (const args of [['--root', dirname(projectRoot)], ['--root', '.pbai4devs'], ['--root', 'examples'], ['--root', 'examples/custom'], ['--unknown']]) {
+    const result = spawnSync(process.execPath, [script, ...args], { encoding: 'utf8' });
+    assert.ifError(result.error);
+    assert.equal(result.status, 2);
+    assert.equal(result.stdout, '');
+    assert.equal(typeof JSON.parse(result.stderr).error, 'string');
+  }
+});
+
+test('classifica sinais de maturidade sem confundir planejamento com produto funcionando', t => {
+  const { directory, file, run } = fixture(t);
+  const state = stage => file('.pbai4devs/estado/configuracao/ESTADO.md', `---\npreparacao: concluido\nconfiguracao_tecnica: ${stage}\ndocumentos:\n  prd: docs/PRD.md\n  ux_ui: docs/UX.md\n  design: docs/DESIGN.md\n  releases: docs/releases\n---\n# Estado\n`);
+  assert.equal(run().report.maturity.level, 'preparacao');
+  state('pendente'); file('docs/PRD.md', '---\nstatus: rascunho\n---\n# PRD\n');
+  assert.equal(run().report.maturity.level, 'descoberta');
+  for (const name of ['PRD', 'DESIGN']) file(`docs/${name}.md`, `---\nstatus: aprovado\n---\n# ${name}\n`);
+  file('docs/UX.md', '---\nstatus: nao-aplicavel\n---\n# UX\n');
+  assert.equal(run().report.maturity.level, 'planejado');
+  file('package.json', '{"scripts":{"test":"node --test"}}'); file('src/main.mjs', 'export const answer = 42;');
+  assert.equal(run().report.maturity.level, 'implementacao');
+  for (const name of ['.agents', '.agent', '.gemini', '.claude', '.codex', '.cursor', '.github', '.opencode', '.vscode', 'tests', 'infra']) directory(name);
+  for (const name of ['.gitignore', '.gitattributes', '.editorconfig', '.dockerignore', 'README.md', 'Makefile']) file(name);
+  file('infra/compose/compose.local.yml', 'services: {}\n'); state('concluido');
+  assert.equal(run('--check').report.maturity.level, 'configurado');
+  file('docs/releases/v1/RELEASE.md', '---\nstatus: publicado\n---\n# Release\n');
+  const result = run('--check'); assert.equal(result.status, 0);
+  assert.equal(result.report.maturity.level, 'manutencao');
+  assert.equal(result.report.maturity.released, true);
+  assert.match(result.report.maturity.limits[0], /nao substitui/);
+});
+
+test('exemplos e caches Playwright não viram aplicação do projeto real', t => {
+  const { file, run } = fixture(t);
+  for (const folder of ['examples/generated/a', 'examples/fixture', 'tmp/examples/a', 'TEMP/project', '.PLAYWRIGHT-MCP', 'playwright-results']) {
+    file(`${folder}/package.json`, '{}'); file(`${folder}/main.mjs`, 'export const fake=1;');
+  }
+  file('.PLAYWRIGHT-state.js', 'export const transient = true;');
+  const report = run().report;
+  assert.equal(report.mode, 'agentes-sem-aplicacao');
+  assert.deepEqual(report.manifests, []); assert.deepEqual(report.sources, []);
+});
+
+test('aceita inspecionar cenário em examples/generated sem liberar outras pastas', t => {
+  const base = join(projectRoot, 'examples/generated'); mkdirSync(base, { recursive: true });
+  const root = mkdtempSync(join(base, 'inspector-fixture-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  writeFileSync(join(root, 'package.json'), '{}');
+  const result = spawnSync(process.execPath, [script, '--root', root], { encoding: 'utf8' });
+  assert.ifError(result.error); assert.equal(result.status, 0, result.stderr);
+  assert.equal(JSON.parse(result.stdout).mode, 'aplicacao-detectada');
+});
+
+test('status arbitrários e referências fora da raiz não expõem dados da configuração', t => {
+  const { file, run } = fixture(t); const secret = 'PRIVATE_STATUS_192819';
+  file('.pbai4devs/estado/configuracao/ESTADO.md', `---\npreparacao: ${secret}\nconfiguracao_tecnica: ${secret}\ndocumentos:\n  prd: ../outside.md\n  design: docs/DESIGN.md\n---\n# Estado\n`);
+  file('docs/DESIGN.md', `---\nstatus: ${secret}\n---\n# Design\n`);
+  const result = run(); assert.equal(result.status, 0);
+  assert.equal(result.report.maturity.planning.prd.path, null);
+  assert.equal(result.report.maturity.planning.ready, false);
+  assert.ok(!result.stdout.includes(secret));
+});

package/.pbai4devs/scripts/lib/README.md

@@ -0,0 +1,9 @@
+---
+description: Utilitários mínimos compartilhados das automações Node.js.
+---
+
+# Utilitários
+
+`runtime.mjs` centraliza o requisito Node.js 24+, a raiz do repositório e a
+identificação do arquivo executado. Não instala runtimes nem configura a máquina.
+Também procura executáveis opcionais no PATH sem iniciar um shell.

package/.pbai4devs/scripts/lib/adapters.mjs

@@ -0,0 +1,135 @@
+import { lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { resourcePath } from './resource-path.mjs';
+import { isGeneratedOutput } from './gitignore.mjs';
+
+const policy = JSON.parse(readFileSync(new URL('../../templates/clients/ADAPTERS.json', import.meta.url), 'utf8'));
+const kinds = new Set(['skills', 'agents', 'commands', 'rules']);
+const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'agente', 'prompt', 'instrucoes']);
+const entryNames = new Set(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+const safeRoot = value => typeof value === 'string' && /^\.[a-z0-9][a-z0-9-]*$/.test(value) && !['.git', '.pbai4devs', '.agent-tests'].includes(value);
+const stringList = value => Array.isArray(value) && value.every(item => typeof item === 'string');
+if (policy.schemaVersion !== 1 || !Array.isArray(policy.adapters) || !policy.adapters.length || !stringList(policy.entrypoints) || policy.entrypoints.some(name => !entryNames.has(name))) throw new Error('Politica de clientes invalida.');
+const ids = new Set(), roots = new Set(), aliases = {};
+for (const adapter of policy.adapters) {
+  if (!adapter || typeof adapter.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(adapter.id) || adapter.id === 'all' || ids.has(adapter.id) || typeof adapter.name !== 'string' || !safeRoot(adapter.root) || roots.has(adapter.root) || !adapter.formats || Object.entries(adapter.formats).some(([kind, layout]) => !kinds.has(kind) || !layouts.has(layout))) throw new Error('Adaptador invalido.');
+  if (/[\r\n]/.test(adapter.name) || typeof adapter.reason !== 'string' || /[\r\n]/.test(adapter.reason) || (adapter.discovery !== undefined && adapter.discovery !== 'antigravity')) throw new Error('Descricao ou descoberta de adaptador invalida.');
+  for (const field of ['aliases', 'requires', 'extraRoots', 'entrypoints', 'sources']) if (!stringList(adapter[field])) throw new Error('Lista invalida no adaptador: ' + field);
+  if (adapter.extraRoots.some(root => !safeRoot(root)) || adapter.entrypoints.some(name => !entryNames.has(name)) || adapter.sources.some(url => !url.startsWith('https://'))) throw new Error('Caminho ou fonte invalida no adaptador.');
+  for (const field of ['agentMetadata', 'ruleMetadata']) if (adapter[field] !== undefined && !/^[a-z0-9-]+\.ya?ml$/.test(adapter[field])) throw new Error('Metadados invalidos no adaptador.');
+  ids.add(adapter.id); roots.add(adapter.root);
+}
+for (const adapter of policy.adapters) {
+  if (adapter.requires.some(id => !ids.has(id))) throw new Error('Dependencia de adaptador desconhecida.');
+  for (const alias of adapter.aliases) {
+    if (!/^[a-z][a-z0-9-]*$/.test(alias) || ids.has(alias) || alias === 'all' || Object.hasOwn(aliases, alias)) throw new Error('Alias de adaptador invalido.');
+    aliases[alias] = adapter.id;
+  }
+}
+export const adapters = Object.freeze(policy.adapters.map(adapter => Object.freeze(adapter)));
+export const availableClients = Object.freeze([
+  Object.freeze({ id: 'all', name: 'Todos os clientes', aliases: Object.freeze([]) }),
+  ...adapters.map(({ id, name, root, aliases }) => Object.freeze({ id, name, root, aliases })),
+]);
+export const adapterRoots = Object.freeze([...new Set(adapters.flatMap(adapter => [adapter.root, ...adapter.extraRoots]))]);
+
+export function normalizeClients(input) {
+  if (input === undefined) return ['all'];
+  const values = typeof input === 'string' ? [input] : input;
+  if (!Array.isArray(values) || !values.length || values.some(value => typeof value !== 'string')) throw new Error('Selecione ao menos um cliente valido.');
+  const selected = new Set();
+  for (const value of values) for (const part of value.split(',')) {
+    const requested = part.trim().toLowerCase(), id = aliases[requested] ?? requested;
+    if (!availableClients.some(client => client.id === id)) throw new Error('Cliente desconhecido: ' + (part || '(vazio)'));
+    selected.add(id);
+  }
+  if (selected.has('all')) {
+    if (selected.size !== 1) throw new Error('all nao pode ser combinado com outros clientes.');
+    return ['all'];
+  }
+  return adapters.filter(adapter => selected.has(adapter.id)).map(adapter => adapter.id);
+}
+
+export function resolveAdapters(input) {
+  const clients = normalizeClients(input), all = clients.includes('all');
+  const requested = all ? adapters.map(adapter => adapter.id) : clients;
+  const selected = new Set(requested);
+  for (const id of selected) for (const required of adapters.find(adapter => adapter.id === id).requires) selected.add(required);
+  const resolved = adapters.filter(adapter => selected.has(adapter.id));
+  const roots = [...new Set(resolved.flatMap(adapter => [adapter.root, ...adapter.extraRoots]))];
+  const selectedEntries = new Set([...policy.entrypoints, ...adapters.filter(adapter => requested.includes(adapter.id)).flatMap(adapter => adapter.entrypoints)]);
+  const entrypoints = [...entryNames].filter(name => selectedEntries.has(name));
+  return { clients, adapters: resolved, roots, entrypoints };
+}
+const principal = { skills: 'SKILL.md', agents: 'AGENT.md', commands: 'COMMAND.md', rules: 'RULE.md' };
+const stat = path => { try { return lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+
+function checked(root, relative) {
+  let path = root;
+  for (const part of relative.split('/')) {
+    if (!part || part === '.' || part === '..') throw new Error(`Caminho de adaptador invalido: ${relative}`);
+    if (stat(path)?.isDirectory() && readdirSync(path).some(name => name.toLowerCase() === part.toLowerCase() && name !== part)) throw new Error(`Capitalizacao ambigua: ${relative}`);
+    path = join(path, part);
+    if (stat(path)?.isSymbolicLink()) throw new Error(`Link simbolico no adaptador: ${relative}`);
+  }
+  return path;
+}
+
+function sources(root, kind) {
+  const result = [];
+  function visit(relative) {
+    const path = checked(root, relative);
+    const item = stat(path);
+    if (!item) return;
+    if (!item.isDirectory()) throw new Error(`Diretorio de recursos invalido: ${relative}`);
+    for (const name of readdirSync(path).sort()) {
+      const child = `${relative}/${name}`, file = checked(root, child), info = stat(file);
+      if (isGeneratedOutput(child, info.isDirectory())) continue;
+      if (info.isDirectory()) visit(child);
+      else if (info.isFile() && name === principal[kind]) result.push(child);
+    }
+  }
+  visit(`.pbai4devs/${kind}`);
+  return result;
+}
+
+export function adapterManifest(root, { clients } = {}) {
+  const selection = resolveAdapters(clients);
+  root = realpathSync(resolve(root));
+  const rows = ['# Gerado por AgentDevKit; sincronizacao instalada nao depende do pacote npm.', '# tipo|cliente|recurso ou layout|formato ou metadados'];
+  const resources = Object.fromEntries(Object.keys(principal).map(kind => [kind, sources(root, kind)]));
+  for (const adapter of selection.adapters) {
+    rows.push(`# ${adapter.id}: ${adapter.reason}`, `agente|${adapter.root}|agrupado`);
+    for (const [kind, mode] of Object.entries(adapter.formats)) rows.push(`formato|${adapter.root}|${kind}|${mode}`);
+    if (adapter.discovery) rows.push(`descoberta|${adapter.root}|${adapter.discovery}`);
+    for (const [kind, key] of [['agents', 'agentMetadata'], ['rules', 'ruleMetadata']]) {
+      if (!adapter[key]) continue;
+      for (const source of resources[kind]) {
+        const metadata = `${source.slice(0, source.lastIndexOf('/'))}/${adapter[key]}`;
+        if (!stat(checked(root, metadata))?.isFile()) continue;
+        const target = `${adapter.root}/${resourcePath(source, kind, adapter.formats[kind] || 'agrupado')}`;
+        rows.push(`nativo|${target}|${source}|${metadata}`);
+      }
+    }
+  }
+  if (selection.roots.includes('.vscode')) rows.push('gitignore|.vscode');
+  return rows.join('\n') + '\n';
+}
+
+// Somente configura a politica. O chamador decide quando planejar/aplicar o sync.
+export function writeAdapterManifest(root, { clients } = {}) {
+  const selection = resolveAdapters(clients);
+  root = realpathSync(resolve(root));
+  const relative = '.pbai4devs/espelhos.conf';
+  const file = checked(root, relative), content = adapterManifest(root, { clients: selection.clients });
+  const info = stat(file);
+  if (info && !info.isFile()) throw new Error('espelhos.conf deve ser arquivo regular.');
+  const result = { clients: selection.clients, roots: selection.roots, entrypoints: selection.entrypoints };
+  if (info && readFileSync(file, 'utf8') === content) return { changed: [], ...result };
+  mkdirSync(dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${randomUUID()}`;
+  try { writeFileSync(temporary, content, { flag: 'wx' }); renameSync(temporary, file); }
+  finally { rmSync(temporary, { force: true }); }
+  return { changed: [relative], ...result };
+}