@pathbit/agentdevkit 0.0.0-stage → 0.0.5

package/.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs

@@ -0,0 +1,455 @@
+#!/usr/bin/env node
+// Definicoes versionadas por ferramenta; pacotes e estado permanecem locais.
+import { existsSync, readFileSync, writeFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, realpathSync, openSync, readSync, closeSync, chmodSync, readdirSync, lstatSync, rmdirSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve, delimiter, isAbsolute, relative, extname, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { projectRoot, requireNode, isMain } from '../lib/runtime.mjs';
+
+const registry = 'https://registry.npmjs.org/';
+const versionPattern = /^\d+\.\d+\.\d+(?:-[\w.-]+)?$/;
+const json = file => JSON.parse(readFileSync(file, 'utf8'));
+const fail = (message, exitCode) => { const error = new Error(message); if (Number.isInteger(exitCode)) error.exitCode = exitCode; throw error; };
+const failureCode = error => Number.isInteger(error?.exitCode) && error.exitCode > 0 ? error.exitCode : 1;
+
+function selectTools(catalog, selected) {
+  const grouped = Object.keys(catalog).filter(name => catalog[name].group === selected);
+  const names = selected === 'all' ? Object.keys(catalog) : selected === 'base' ? grouped : Object.hasOwn(catalog, selected) || !grouped.length ? [selected] : grouped;
+  if (!names.length) fail(`Nenhuma ferramenta definida para: ${selected}`);
+  return names;
+}
+
+export function platformKey(platform = process.platform, arch = process.arch) {
+  if (!['darwin', 'linux', 'win32'].includes(platform) || !['arm64', 'x64'].includes(arch)) fail(`SO/arquitetura nao suportado: ${platform}-${arch}`);
+  return `${platform}-${arch}`;
+}
+
+export function validateToolConfig(name, value) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || value?.name !== name) fail(`Nome de ferramenta invalido: ${name}`);
+  if (typeof value.description !== 'string' || !value.description.trim() || value.description.includes('\0')) fail(`Descricao ausente ou invalida: ${name}`);
+  const download = value.download;
+  if (download?.provider !== 'npm' || download.registry !== registry || download.channel !== 'latest') fail(`Download nao suportado: ${name}`);
+  if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(download.package || '') || !/^[\w.-]+\/[\w.-]+$/.test(download.repository || '')) fail(`Origem invalida: ${name}`);
+  if (!/^[a-z][a-z0-9-]*$/.test(value.group || '') || !Array.isArray(value.platforms) || !value.platforms.length || new Set(value.platforms).size !== value.platforms.length || value.platforms.some(item => !/^(?:darwin|linux|win32)-(?:arm64|x64)$/.test(item))) fail(`Grupo/plataformas invalidos: ${name}`);
+  if (!Array.isArray(value.probe) || !value.probe.length || value.probe.some(item => typeof item !== 'string' || item.includes('\0')) || (value.probeInput !== undefined && (typeof value.probeInput !== 'string' || value.probeInput.includes('\0')))) fail(`Verificacao invalida: ${name}`);
+  if (value.binary !== undefined && (typeof value.binary !== 'string' || !/^[\w.-]+$/.test(value.binary))) fail(`Executavel invalido: ${name}`);
+  if (value.executables !== undefined) {
+    if (!value.executables || typeof value.executables !== 'object' || Array.isArray(value.executables) || !Object.keys(value.executables).length) fail(`Mapa de executaveis invalido: ${name}`);
+    for (const [platform, files] of Object.entries(value.executables)) {
+      if (!value.platforms.includes(platform) || !/^(?:darwin|linux)-(?:arm64|x64)$/.test(platform)) fail(`Plataforma de executaveis invalida: ${name}/${platform}`);
+      if (!Array.isArray(files) || !files.length || new Set(files).size !== files.length) fail(`Lista de executaveis invalida: ${name}/${platform}`);
+      for (const file of files) {
+        if (typeof file !== 'string' || !file || file.includes('\0') || file.includes('\\') || file.includes(':') || file.split('/').some(part => !part || part === '.' || part === '..')) fail(`Caminho de executavel deve ser relativo ao pacote: ${name}`);
+      }
+    }
+  }
+  if (value.scripts?.entry !== 'SCRIPT.mjs' || Object.keys(value.scripts).length !== 1) fail(`Script invalido; use scripts.entry=SCRIPT.mjs: ${name}`);
+  if (value.nodeMinimum !== undefined) fail(`nodeMinimum foi substituido pelo requisito comum Node >=24: ${name}`);
+  const environmentKeys = new Set();
+  for (const field of ['env', 'envPaths']) {
+    if (value[field] === undefined) continue;
+    if (!value[field] || typeof value[field] !== 'object' || Array.isArray(value[field])) fail(`${field} invalido: ${name}`);
+    for (const [key, content] of Object.entries(value[field])) {
+      const normalized = key.toUpperCase();
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || ['HOME', 'CODEX_HOME', 'PATH'].includes(normalized)) fail(`Variavel de ambiente protegida ou invalida: ${key}`);
+      if (environmentKeys.has(normalized)) fail(`Variavel de ambiente duplicada: ${key}`);
+      environmentKeys.add(normalized);
+      if (typeof content !== 'string' || content.includes('\0')) fail(`Valor de ambiente invalido: ${key}`);
+    }
+  }
+  if (value.envPaths !== undefined) {
+    for (const [key, location] of Object.entries(value.envPaths)) {
+      if (!location || location.includes('\\') || /^[A-Za-z]:/.test(location) || location.split('/').some(part => !part || part === '.' || part === '..')) fail(`Caminho de ambiente deve ser relativo: ${key}`);
+    }
+  }
+  let source; try { source = new URL(value.source); } catch { fail(`Documentacao invalida: ${name}`); }
+  if (source.protocol !== 'https:' || source.username || source.password) fail(`Documentacao invalida: ${name}`);
+  return value;
+}
+
+export function toolActions(name, entry) {
+  validateToolConfig(name, entry);
+  const descriptions = {
+    install: 'Instala ou reutiliza uma instalacao saudavel.',
+    update: 'Consulta latest e atualiza com rollback em caso de falha.',
+    check: 'Executa o probe local sem instalar nem consultar latest.',
+    info: 'Mostra configuracao, plataforma, runtime e versao registrada.',
+    run: 'Executa o CLI instalado com os argumentos informados.',
+    unlock: 'Remove apenas um lock local cujo processo comprovadamente terminou.',
+  };
+  return Object.fromEntries(Object.entries(descriptions).map(([action, description]) => [action, {
+    executor: 'node', argv: ['node', `.pbai4devs/tools/${name}/${entry.scripts.entry}`, action], description,
+    ...(action === 'run' ? { requiresArguments: true } : {}),
+  }]));
+}
+
+export function toolWrapper(name) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) fail(`Nome de ferramenta invalido: ${name}`);
+  return `#!/usr/bin/env node\nimport { main } from '../../scripts/preparar-ferramentas/SCRIPT.mjs';\n\ntry { process.exitCode = await main(['--tool', ${JSON.stringify(name)}, ...process.argv.slice(2)]); }\ncatch (error) { console.error(error.message); process.exitCode = 1; }\n`;
+}
+
+function sourcePath(root, name) {
+  const file = resolve(root, name); const child = relative(root, file);
+  if (isAbsolute(child) || child === '..' || child.startsWith(`..${sep}`)) fail(`Caminho fora da raiz: ${name}`);
+  let current = root;
+  for (const part of child.split(sep).filter(Boolean)) {
+    current = join(current, part);
+    try { if (lstatSync(current).isSymbolicLink()) fail(`Fonte de ferramenta nao pode ser um link: ${name}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return file;
+}
+
+export function loadCatalog(root = projectRoot) {
+  root = realpathSync(root);
+  const home = sourcePath(root, '.pbai4devs/tools'); const catalog = Object.create(null);
+  if (!existsSync(home)) return catalog;
+  for (const item of readdirSync(home, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (item.name.startsWith('.') || ['bin', 'npm-cache'].includes(item.name)) continue;
+    const folder = sourcePath(root, join('.pbai4devs/tools', item.name));
+    if (!lstatSync(folder).isDirectory()) continue;
+    const file = sourcePath(root, join('.pbai4devs/tools', item.name, 'TOOL.json'));
+    if (!existsSync(file) || !lstatSync(file).isFile()) fail(`TOOL.json ausente ou invalido: ${item.name}`);
+    const entry = validateToolConfig(item.name, json(file));
+    const script = sourcePath(root, join('.pbai4devs/tools', item.name, entry.scripts.entry));
+    if (!existsSync(script) || !lstatSync(script).isFile()) fail(`Script ausente ou invalido: ${item.name}/${entry.scripts.entry}`);
+    if (readFileSync(script, 'utf8').replace(/\r\n?/g, '\n') !== toolWrapper(item.name)) fail(`Apontamento de ferramenta divergente: ${item.name}; use toolWrapper(nome).`);
+    catalog[item.name] = entry;
+  }
+  return catalog;
+}
+
+export function validateRelease(name, entry, release) {
+  const expected = entry.download.package;
+  const repository = typeof release.repository === 'string' ? release.repository : release.repository?.url;
+  if (release.name !== expected || !versionPattern.test(release.version || '')) fail(`Nome/versao invalido no registro: ${name}`);
+  const origin = new URL(repository?.replace(/^git\+/, '').replace(/\.git$/, ''));
+  if (origin.protocol !== 'https:' || origin.hostname !== 'github.com' || origin.pathname !== `/${entry.download.repository}`) fail('Repositorio de origem divergente.');
+  const tarball = new URL(release.dist?.tarball);
+  if (tarball.origin !== registry.slice(0, -1) || !decodeURIComponent(tarball.pathname).startsWith(`/${expected}/-/`) || tarball.search || tarball.hash || !release.dist?.integrity?.startsWith('sha512-')) fail('Tarball ou integridade invalida.');
+  return release;
+}
+
+function npmCli(runtime, environment) {
+  const candidates = [join(dirname(runtime.file), 'node_modules/npm/bin/npm-cli.js'), join(dirname(runtime.file), '../lib/node_modules/npm/bin/npm-cli.js'), environment.npm_execpath];
+  for (const entry of (environment.PATH || '').split(delimiter)) for (const name of ['npm', 'npm.cmd']) {
+    const file = join(entry, name);
+    if (existsSync(file)) candidates.push(realpathSync(file), join(entry, 'node_modules/npm/bin/npm-cli.js'));
+  }
+  const cli = candidates.find(file => file && file.endsWith('npm-cli.js') && existsSync(file));
+  if (!cli) fail('npm nao encontrado junto do Node; siga os pre-requisitos do projeto.');
+  return cli;
+}
+
+export function binaryInvocation(prefix, name, args = [], binaryName = name.split('/').at(-1), node = process.execPath) {
+  const base = join(prefix, 'node_modules', name); const pkg = json(join(base, 'package.json'));
+  const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[binaryName];
+  if (typeof bin !== 'string' || !bin || bin.includes('\0')) fail(`Executavel ausente ou invalido: ${name}`);
+  const binary = resolve(base, bin); const traversal = relative(base, binary);
+  if (isAbsolute(traversal) || traversal === '..' || traversal.startsWith('..' + (process.platform === 'win32' ? '\\' : '/'))) fail('Executavel fora do pacote.');
+  const resolved = relative(prefix, realpathSync(binary));
+  if (isAbsolute(resolved) || resolved === '..' || resolved.startsWith('..' + (process.platform === 'win32' ? '\\' : '/'))) fail('Executavel fora da instalacao local.');
+  const header = Buffer.alloc(128); const handle = openSync(binary, 'r');
+  try { readSync(handle, header, 0, header.length, 0); } finally { closeSync(handle); }
+  return /^#![^\n]*\bnode\b/.test(header.toString()) || ['.js', '.mjs', '.cjs'].includes(extname(binary)) ? [node, [binary, ...args]] : [binary, args];
+}
+
+export function toolEnvironment(entry, local, runtime) {
+  const environment = Object.assign(Object.create(null), process.env);
+  const set = (key, value) => {
+    if (process.platform === 'win32') for (const existing of Object.keys(environment)) if (existing.toUpperCase() === key.toUpperCase()) delete environment[existing];
+    environment[key] = value;
+  };
+  for (const [key, value] of Object.entries(entry.env || {})) set(key, value);
+  for (const [key, location] of Object.entries(entry.envPaths || {})) {
+    let directory = resolve(local);
+    for (const part of ['', ...location.split('/')]) {
+      if (part) directory = join(directory, part);
+      try { if (lstatSync(directory).isSymbolicLink()) fail(`Caminho de ambiente nao pode ser um link: ${key}`); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    set(key, resolve(local, location));
+  }
+  if (runtime) { const path = environment.PATH || environment.Path || ''; set('PATH', `${dirname(runtime.file)}${path ? delimiter + path : ''}`); }
+  return environment;
+}
+
+function execute(prefix, entry, args, capture = false, input, environment, runtime) {
+  const [file, options] = binaryInvocation(prefix, entry.download.package, args, entry.binary || entry.name, runtime.file);
+  const result = spawnSync(file, options, { stdio: capture ? 'pipe' : 'inherit', cwd: capture ? prefix : undefined, input, env: environment, encoding: 'utf8', timeout: capture ? 30000 : undefined, windowsHide: true });
+  if (result.error) throw result.error;
+  if (capture && result.status !== 0) fail(`${entry.name}: ${result.stderr?.trim().slice(0, 400) || result.stdout?.trim().slice(0, 400) || `falha ${result.status}`}`, result.status ?? 1);
+  return result.status ?? 1;
+}
+
+function prepareExecutables(prefix, entry, platform) {
+  const files = entry.executables?.[platform];
+  if (!files || process.platform === 'win32') return;
+  const within = (base, file) => { const child = relative(base, file); return !isAbsolute(child) && child !== '..' && !child.startsWith(`..${sep}`); };
+  const stage = realpathSync(prefix);
+  const packageRoot = realpathSync(join(prefix, 'node_modules', entry.download.package));
+  if (!within(stage, packageRoot)) fail(`Pacote fora do staging: ${entry.name}`);
+  const targets = files.map(file => {
+    const target = realpathSync(join(packageRoot, file));
+    if (!within(packageRoot, target)) fail(`Executavel fora do pacote: ${entry.name}/${file}`);
+    const info = lstatSync(target);
+    if (!info.isFile()) fail(`Executavel nao e arquivo regular: ${entry.name}/${file}`);
+    return { target, mode: (info.mode & 0o777) | 0o111 };
+  });
+  for (const { target, mode } of targets) chmodSync(target, mode);
+}
+
+export class ToolManager {
+  constructor({ root = projectRoot, catalog, fetchRelease, install, npm = npmCli, nodeVersion = process.versions.node, platform = process.platform, arch = process.arch } = {}) {
+    this.root = resolve(root); this.home = join(this.root, '.pbai4devs/tools'); this.target = `${platform}-${arch}`;
+    this.nodeVersion = nodeVersion; this.npm = npm;
+    this.catalog = catalog ?? loadCatalog(this.root);
+    for (const [name, entry] of Object.entries(this.catalog)) validateToolConfig(name, entry);
+    this.fetchRelease = fetchRelease || (async (name, entry) => {
+      const response = await fetch(`${entry.download.registry}${encodeURIComponent(entry.download.package)}/${entry.download.channel}`, { signal: AbortSignal.timeout(20000) });
+      if (!response.ok) fail(`Registro indisponivel: HTTP ${response.status}`);
+      return response.json();
+    });
+    this.installPackage = install || ((prefix, packageName, version, entry, runtime) => {
+      const environment = toolEnvironment(entry, this.local(entry.name), runtime);
+      const result = spawnSync(runtime.file, [this.npm(runtime, environment), 'install', '--prefix', prefix, '--cache', join(this.home, '.cache/npm'), '--registry', entry.download.registry, '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--save-exact', `${packageName}@${version}`], {
+        cwd: prefix, encoding: 'utf8', timeout: 180000,
+        env: { ...environment, npm_config_engine_strict: 'true', npm_config_update_notifier: 'false', PUPPETEER_SKIP_DOWNLOAD: 'true', PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1' }
+      });
+      if (result.error || result.status !== 0) fail(`npm: ${result.error?.message || result.stderr?.trim() || result.status}`, result.status ?? 1);
+    });
+  }
+  entry(name) {
+    if (!Object.hasOwn(this.catalog, name)) fail(`Ferramenta desconhecida: ${name}`);
+    return this.catalog[name];
+  }
+  runtime(name) {
+    const entry = this.entry(name);
+    if (!entry.platforms.includes(this.target)) fail(`Plataforma nao suportada por ${name}: ${this.target}`);
+    requireNode(24, this.nodeVersion);
+    return { file: process.execPath, version: process.version };
+  }
+  preflight(names) {
+    const issues = [];
+    for (const name of names) try { this.runtime(name); } catch (error) { issues.push(`${name}: ${error.message}`); }
+    if (issues.length) fail(`Pre-requisitos indisponiveis; nenhuma ferramenta foi alterada:\n${issues.join('\n')}`);
+  }
+  checkNpm() {
+    requireNode(24, this.nodeVersion);
+    const runtime = { file: process.execPath, version: process.version };
+    const environment = { ...toolEnvironment({}, this.home, runtime), npm_config_update_notifier: 'false' };
+    let file;
+    try { file = realpathSync(this.npm(runtime, environment)); }
+    catch (error) { fail(`npm indisponivel: ${error.message}. Instale Node.js 24+ com npm: https://nodejs.org/en/download .`); }
+    if (!lstatSync(file).isFile()) fail(`npm nao e um arquivo: ${file}`);
+    const result = spawnSync(runtime.file, [file, '--version'], { cwd: this.root, env: environment, encoding: 'utf8', timeout: 15000, windowsHide: true });
+    const version = result.stdout?.trim();
+    if (result.error || result.status !== 0 || !versionPattern.test(version || '')) fail(`npm indisponivel: ${result.error?.message || result.stderr?.trim() || version || result.status}. Instale Node.js 24+ com npm: https://nodejs.org/en/download .`, result.status || 1);
+    return { path: file, version };
+  }
+  async setup(selected = 'all') {
+    const names = selectTools(this.catalog, selected);
+    const explicit = !['all', 'base'].includes(selected) && Object.hasOwn(this.catalog, selected);
+    const results = new Map(names.map(name => [name, null])); const compatible = [];
+    let npm = null;
+    for (const name of names) {
+      if (this.entry(name).platforms.includes(this.target)) compatible.push(name);
+      else results.set(name, { name, status: explicit ? 'failed' : 'not-applicable', phase: 'platform', exitCode: explicit ? 1 : null, reason: `Plataforma nao suportada: ${this.target}` });
+    }
+    try { if (compatible.length) { this.preflight(compatible); npm = this.checkNpm(); } }
+    catch (error) { for (const name of compatible) results.set(name, { name, status: 'failed', phase: 'preflight', exitCode: failureCode(error), reason: error.message }); }
+    if (npm) for (const name of compatible) {
+      let phase = 'install';
+      try {
+        const installed = await this.install(name); phase = 'check';
+        const checked = this.check(name);
+        results.set(name, { name, status: 'passed', phase, exitCode: 0, version: checked.version, changed: installed.changed });
+      } catch (error) { results.set(name, { name, status: 'failed', phase, exitCode: failureCode(error), reason: error.message }); }
+    }
+    const entries = [...results.values()];
+    const summary = { passed: entries.filter(item => item.status === 'passed').length, failed: entries.filter(item => item.status === 'failed').length, notApplicable: entries.filter(item => item.status === 'not-applicable').length };
+    return { mode: 'setup', selection: selected, platform: this.target, node: process.version, nodePath: process.execPath, npm, results: entries, summary, status: summary.failed ? 'failed' : summary.passed ? 'passed' : 'not-applicable', exitCode: summary.failed ? 1 : 0 };
+  }
+  local(name) { this.entry(name); return join(this.home, name, '.local'); }
+  current(name) {
+    this.entry(name);
+    const local = this.local(name); const legacy = join(this.home, name);
+    const base = existsSync(join(local, 'CURRENT.json')) ? local : legacy;
+    const file = join(base, 'CURRENT.json');
+    if (!existsSync(file)) fail(`Ferramenta ausente: ${name}; execute install ${name}.`);
+    const info = json(file);
+    if (info.name !== name || info.platform !== this.target || !versionPattern.test(info.version || '')) fail(`Instalacao incompativel: ${name}`);
+    return { ...info, layout: base === local ? 'local' : 'legacy', prefix: join(base, 'versions', `${info.version}-${this.target}`) };
+  }
+  check(name) {
+    const entry = this.entry(name); const runtime = this.runtime(name); const info = this.current(name);
+    const pkg = json(join(info.prefix, 'node_modules', entry.download.package, 'package.json'));
+    if (pkg.name !== entry.download.package || pkg.version !== info.version) fail(`Versao local divergente: ${name}`);
+    execute(info.prefix, entry, entry.probe, true, entry.probeInput, toolEnvironment(entry, this.local(name), runtime), runtime);
+    return info;
+  }
+  info(name) {
+    const config = this.entry(name); let installed = null; let issue; let runtime = null;
+    try { runtime = this.runtime(name); } catch (error) { issue = error.message; }
+    try { const current = this.current(name); installed = { version: current.version, platform: current.platform, layout: current.layout }; }
+    catch (error) { issue ??= error.message; }
+    return { ...config, platform: this.target, supported: runtime !== null, runtime: runtime ? { path: runtime.file, version: runtime.version } : null, installed, ...(issue ? { issue } : {}) };
+  }
+  launchers(name) {
+    this.entry(name);
+    const bin = sourcePath(this.root, join(this.home, 'bin'));
+    const launcher = sourcePath(this.root, join(bin, `${name}.mjs`));
+    mkdirSync(bin, { recursive: true });
+    writeFileSync(launcher, `#!/usr/bin/env node\nimport { main } from '../../scripts/preparar-ferramentas/SCRIPT.mjs';\ntry { process.exitCode = await main(['run', ${JSON.stringify(name)}, ...process.argv.slice(2)]); }\ncatch (error) { console.error(error.message); process.exitCode = 1; }\n`);
+    chmodSync(launcher, 0o755);
+    for (const legacy of [name, `${name}.cmd`, `${name}.ps1`, `${name}.sh`]) rmSync(join(bin, legacy), { force: true });
+  }
+  migrate(name) {
+    const local = this.local(name); const tool = join(this.home, name);
+    const legacyState = join(tool, 'CURRENT.json'); const legacyVersions = join(tool, 'versions');
+    if (existsSync(legacyState)) {
+      if (existsSync(join(local, 'CURRENT.json')) || (existsSync(join(local, 'versions')) && readdirSync(join(local, 'versions')).length)) fail(`Layouts local e antigo coexistem: ${name}; revise antes de migrar.`);
+      if (!existsSync(legacyVersions)) fail(`Versoes antigas ausentes: ${name}`);
+      if (existsSync(join(local, 'versions'))) rmdirSync(join(local, 'versions'));
+      renameSync(legacyVersions, join(local, 'versions'));
+      try { renameSync(legacyState, join(local, 'CURRENT.json')); }
+      catch (error) { renameSync(join(local, 'versions'), legacyVersions); throw error; }
+    }
+    const oldCache = join(this.home, 'npm-cache');
+    if (existsSync(oldCache)) {
+      const cache = join(this.home, '.cache'); mkdirSync(cache, { recursive: true });
+      try { renameSync(oldCache, join(cache, existsSync(join(cache, 'npm')) ? `npm-legacy-${process.pid}-${Date.now()}` : 'npm')); }
+      catch (error) { if (error.code !== 'ENOENT' || existsSync(oldCache)) throw error; }
+    }
+  }
+  async withLock(name, action) {
+    const local = this.local(name);
+    for (const directory of [this.home, join(this.home, name), local]) if (existsSync(directory) && lstatSync(directory).isSymbolicLink()) fail(`Diretorio local nao pode ser um link: ${directory}`);
+    mkdirSync(local, { recursive: true }); const lock = join(local, '.update-lock');
+    try { mkdirSync(lock); } catch (error) {
+      if (error.code === 'EEXIST') {
+        const status = this.lockStatus(name);
+        fail(status.state === 'stale' ? `Lock orfao: ${name}; use unlock ${name}.` : `Atualizacao em andamento ou lock indeterminado: ${name}`);
+      }
+      throw error;
+    }
+    try { writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, hostname: hostname(), startedAt: new Date().toISOString() })); return await action(); }
+    finally { rmSync(lock, { recursive: true, force: true }); }
+  }
+  lockStatus(name) {
+    const lock = sourcePath(this.root, join(this.local(name), '.update-lock'));
+    if (!existsSync(lock)) return { state: 'missing', lock };
+    try {
+      if (!lstatSync(lock).isDirectory()) return { state: 'indeterminate', lock };
+      const ownerFile = sourcePath(this.root, join(lock, 'owner.json'));
+      if (!lstatSync(ownerFile).isFile()) return { state: 'indeterminate', lock };
+      const owner = json(ownerFile);
+      if (!Number.isSafeInteger(owner?.pid) || owner.pid <= 0 || owner.pid > 2147483647 || owner.hostname !== hostname()) return { state: 'indeterminate', lock };
+      try { process.kill(owner.pid, 0); return { state: 'active', lock, pid: owner.pid }; }
+      catch (error) { return { state: error.code === 'ESRCH' ? 'stale' : 'indeterminate', lock, pid: owner.pid }; }
+    } catch { return { state: 'indeterminate', lock }; }
+  }
+  unlock(name) {
+    const lock = sourcePath(this.root, join(this.local(name), '.update-lock'));
+    if (!existsSync(lock)) return { name, removed: false, state: 'missing' };
+    const recovery = join(lock, 'recovery.json'), token = randomUUID(); let claimed = false, moved = false;
+    try {
+      const handle = openSync(recovery, 'wx');
+      try { writeFileSync(handle, JSON.stringify({ token })); claimed = true; } finally { closeSync(handle); }
+      const ownerFile = sourcePath(this.root, join(lock, 'owner.json'));
+      const ownerSnapshot = readFileSync(ownerFile, 'utf8');
+      const status = this.lockStatus(name);
+      if (status.state !== 'stale') fail(`Lock ${status.state}: ${name}; nenhum lock foi removido.`);
+      if (json(sourcePath(this.root, recovery)).token !== token || readFileSync(ownerFile, 'utf8') !== ownerSnapshot) fail(`Lock mudou durante a recuperacao: ${name}.`);
+      const retired = sourcePath(this.root, join(this.local(name), `.unlocked-${token}`));
+      renameSync(lock, retired); moved = true;
+      rmSync(retired, { recursive: true });
+      return { name, removed: true, state: 'stale' };
+    } finally {
+      if (claimed && !moved) {
+        try { if (json(recovery).token === token) unlinkSync(recovery); } catch { /* O dono pode ter concluido e removido o lock. */ }
+      }
+    }
+  }
+  async install(name) { this.preflight([name]); return this.withLock(name, async () => {
+    this.migrate(name);
+    let installed;
+    try { installed = this.check(name); } catch { /* Ausente ou quebrado: preparar uma instalacao. */ }
+    if (installed) { this.launchers(name); return { ...installed, changed: false }; }
+    return this.updateLocked(name);
+  }); }
+  async update(name) { this.preflight([name]); return this.withLock(name, async () => { this.migrate(name); return this.updateLocked(name); }); }
+  commitState(name, temporary) { renameSync(temporary, join(this.local(name), 'CURRENT.json')); }
+  async updateLocked(name) {
+    const entry = this.entry(name); const runtime = this.runtime(name); const release = validateRelease(name, entry, await this.fetchRelease(name, entry));
+    let installed;
+    try { installed = this.check(name); } catch { /* Ausente ou quebrado: reparar em staging. */ }
+    if (installed?.version === release.version) { this.launchers(name); return { ...installed, changed: false }; }
+    const local = this.local(name); mkdirSync(join(local, 'versions'), { recursive: true });
+    const stage = mkdtempSync(join(local, '.stage-')); const target = join(local, 'versions', `${release.version}-${this.target}`);
+    const temporary = join(local, `CURRENT.${process.pid}.${Date.now()}.json`); let previous; let moved = false;
+    try {
+      this.installPackage(stage, entry.download.package, release.version, entry, runtime);
+      const pkg = json(join(stage, 'node_modules', entry.download.package, 'package.json')); const lock = json(join(stage, 'package-lock.json'));
+      if (pkg.name !== entry.download.package || pkg.version !== release.version || lock.packages?.[`node_modules/${entry.download.package}`]?.integrity !== release.dist.integrity) fail('Pacote instalado nao corresponde ao registro.');
+      prepareExecutables(stage, entry, this.target);
+      execute(stage, entry, entry.probe, true, entry.probeInput, toolEnvironment(entry, local, runtime), runtime);
+      const info = { name, package: entry.download.package, version: release.version, platform: this.target, node: runtime.version, nodePath: runtime.file, source: entry.source, tarball: release.dist.tarball, integrity: release.dist.integrity, checkedAt: new Date().toISOString() };
+      writeFileSync(temporary, `${JSON.stringify(info, null, 2)}\n`);
+      this.launchers(name);
+      if (existsSync(target)) { previous = `${target}.previous-${process.pid}-${Date.now()}`; renameSync(target, previous); }
+      try { renameSync(stage, target); moved = true; this.commitState(name, temporary); }
+      catch (error) { if (moved) rmSync(target, { recursive: true, force: true }); if (previous) renameSync(previous, target); throw error; }
+      return { ...info, layout: 'local', prefix: target, changed: true };
+    } finally { rmSync(stage, { recursive: true, force: true }); rmSync(temporary, { force: true }); }
+  }
+  run(name, args) { const entry = this.entry(name); const runtime = this.runtime(name); return execute(this.current(name).prefix, entry, args, false, undefined, toolEnvironment(entry, this.local(name), runtime), runtime); }
+}
+
+const help = 'Uso: setup [all|grupo|nome]; [install|update|check|info] [base|all|grupo|nome]; list; unlock <nome>; run <nome> [argumentos]; --tool <nome> <acao> [argumentos].';
+const focusedHelp = name => `${name}: setup | install | update | check | info | unlock | run [argumentos]\nsetup instala e verifica; unlock recupera lock local orfao; check verifica; info mostra a configuracao; run executa.`;
+export async function main(input = process.argv.slice(2), manager) {
+  requireNode();
+  const args = [...input]; let focused;
+  if (args[0] === '--tool') { args.shift(); focused = args.shift(); if (!focused) fail('Falta o nome de --tool.'); }
+  const aliases = { '--setup': 'setup', '--update': 'update', '--check': 'check', '--run': 'run', '--info': 'info', '--install': 'install' };
+  const supplied = args.shift(); const mode = aliases[supplied] || supplied || 'help';
+  if (['help', '--help', '-h'].includes(mode)) { console.log(focused ? focusedHelp(focused) : help); return 0; }
+  manager ??= new ToolManager();
+  if (focused) manager.entry(focused);
+  if (mode === 'unlock') {
+    const name = focused || args.shift(); if (!name || args.length) fail('Use unlock <nome> para uma unica ferramenta.');
+    console.log(JSON.stringify(manager.unlock(name))); return 0;
+  }
+  if (mode === 'run') { const name = focused || args.shift(); if (!name) fail('Uso: run <ferramenta> [argumentos]'); return manager.run(name, args); }
+  if (mode === 'list') {
+    if (focused || args.length) fail('list nao aceita argumentos.');
+    for (const name of Object.keys(manager.catalog)) {
+      const info = manager.info(name);
+      console.log(JSON.stringify({ name, group: info.group, platform: info.platform, supported: info.supported, installed: info.installed?.version || null, ...(info.issue ? { issue: info.issue } : {}) }));
+    }
+    return 0;
+  }
+  if (mode === 'setup') {
+    const selected = focused || args.shift() || 'all'; if (args.length) fail('Argumentos excedentes.');
+    const { results, ...summary } = await manager.setup(selected);
+    for (const result of results) console.log(JSON.stringify({ event: 'tool', ...result }));
+    console.log(JSON.stringify({ event: 'summary', ...summary }));
+    return summary.exitCode;
+  }
+  if (!['install', 'update', 'check', 'info'].includes(mode)) fail(help);
+  const selected = focused || args.shift() || 'base'; if (args.length) fail('Argumentos excedentes.');
+  const names = selectTools(manager.catalog, selected);
+  if (mode === 'install' || mode === 'update') manager.preflight?.(names);
+  for (const name of names) {
+    if (mode === 'info') { console.log(JSON.stringify(manager.info(name))); continue; }
+    const info = await manager[mode](name);
+    console.log(`${name}=${info.version}; platform=${info.platform}; ${info.changed ? 'updated' : 'ready'}`);
+  }
+  return 0;
+}
+if (isMain(import.meta.url)) {
+  try { process.exitCode = await main(); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/.pbai4devs/scripts/preparar-ferramentas/tests/FIXTURE.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="pt-BR">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Prova da ferramenta local</title>
+<main>
+  <h1>Prova da ferramenta local</h1>
+  <form>
+    <label>Nome<input name="nome" required></label>
+    <button type="submit">Confirmar</button>
+  </form>
+  <p role="status"></p>
+</main>
+<script>
+document.querySelector('form').onsubmit = event => {
+  event.preventDefault();
+  document.querySelector('[role="status"]').textContent = `Ola, ${event.target.nome.value}`;
+};
+</script>
+</html>

package/.pbai4devs/scripts/preparar-ferramentas/tests/SMOKE_BROWSER.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findExecutable, projectRoot, requireNode } from '../../lib/runtime.mjs';
+
+requireNode();
+const here = dirname(fileURLToPath(import.meta.url));
+const tool = join(projectRoot, '.pbai4devs/tools/agent-browser/SCRIPT.mjs');
+const candidates = [process.env.AGENT_BROWSER_EXECUTABLE_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  process.env.PROGRAMFILES && join(process.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe'),
+  process.env['PROGRAMFILES(X86)'] && join(process.env['PROGRAMFILES(X86)'], 'Google/Chrome/Application/chrome.exe'),
+  process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe'),
+  process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Chromium/Application/chrome.exe'),
+  'google-chrome', 'chromium', 'chromium-browser'].filter(Boolean);
+const browser = candidates.map(name => findExecutable(name)).find(Boolean);
+if (!browser) { console.error('Navegador ausente; defina AGENT_BROWSER_EXECUTABLE_PATH.'); process.exit(69); }
+const output = join(projectRoot, '.agent-tests/tools-browser');
+mkdirSync(output, { recursive: true });
+const session = `agents-tool-smoke-${process.pid}`;
+const run = (args, file, useSession = true) => {
+  const result = spawnSync(process.execPath, [tool, 'run', ...(useSession ? ['--session', session] : []), ...args],
+    { cwd: projectRoot, encoding: 'utf8', timeout: 45000, windowsHide: true });
+  if (file) writeFileSync(join(output, file), `${result.stdout || ''}${result.stderr || ''}`);
+  assert.ifError(result.error);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  return result.stdout.trim();
+};
+const close = () => {
+  const result = spawnSync(process.execPath, [tool, 'run', '--session', session, 'close'],
+    { encoding: 'utf8', timeout: 10000, windowsHide: true });
+  writeFileSync(join(output, 'close.json'), JSON.stringify({ status: result.status, error: result.error?.message, stdout: result.stdout, stderr: result.stderr }, null, 2) + '\n');
+  assert.ifError(result.error);
+  assert.equal(result.status, 0, 'Falha ao encerrar a sessao do navegador; veja close.json.');
+};
+for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => {
+  try { close(); } catch (error) { console.error(error.message); }
+  process.exit(signal === 'SIGINT' ? 130 : 143);
+});
+try {
+  run(['skills', 'get', 'core'], 'guide.txt', false);
+  const fixture = 'data:text/html;charset=utf-8,' + encodeURIComponent(readFileSync(join(here, 'FIXTURE.html'), 'utf8'));
+  run(['--executable-path', browser, 'open', fixture], 'open.txt');
+  run(['snapshot', '-i'], 'snapshot.txt');
+  run(['find', 'label', 'Nome', 'fill', 'Agente'], 'fill.txt');
+  run(['find', 'text', 'Confirmar', 'click'], 'click.txt');
+  run(['snapshot'], 'result.txt');
+  assert.equal(run(['get', 'text', '[role="status"]']), 'Ola, Agente');
+  run(['screenshot', join(output, 'tela.png')], 'screenshot.txt');
+} finally { close(); }
+console.log('agent-browser-functional=passed');

package/.pbai4devs/scripts/preparar-ferramentas/tests/SMOKE_DESKTOP.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Abre apenas um Chrome de teste e lê sua janela por acessibilidade.
+import assert from 'node:assert/strict';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { findExecutable, projectRoot, requireNode } from '../../lib/runtime.mjs';
+
+requireNode();
+const output = join(projectRoot, '.agent-tests/tools-desktop');
+mkdirSync(output, { recursive: true });
+const session = `desktop-smoke-${process.pid}`;
+const title = `Prova desktop ${process.pid}`;
+const application = process.env.AGENT_DESKTOP_TEST_APP || (process.platform === 'darwin' ? 'Google Chrome' : 'chrome');
+const paths = [process.env.AGENT_BROWSER_EXECUTABLE_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  process.env.PROGRAMFILES && join(process.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe'),
+  process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe'),
+  'google-chrome', 'chromium', 'chrome'].filter(Boolean);
+const browserPath = paths.map(path => findExecutable(path)).find(Boolean);
+assert.ok(browserPath, 'Configure AGENT_BROWSER_EXECUTABLE_PATH para um Chrome instalado.');
+
+function run(tool, args, log, allowFailure = false) {
+  const result = spawnSync(process.execPath, [join(projectRoot, '.pbai4devs/tools', tool, 'SCRIPT.mjs'), 'run', ...args],
+    { cwd: projectRoot, encoding: 'utf8', timeout: 30000, windowsHide: true });
+  if (log) writeFileSync(join(output, log), JSON.stringify({ status: result.status, error: result.error?.message, stdout: result.stdout, stderr: result.stderr }, null, 2) + '\n');
+  assert.ifError(result.error);
+  if (!allowFailure) assert.equal(result.status, 0, result.stderr || result.stdout);
+  return result.stdout;
+}
+
+let passed = false;
+try {
+  const html = `<title>${title}</title><h1>Prova controlada</h1><button>Confirmar teste</button>`;
+  run('agent-browser', ['--session', session, '--headed', '--args', '--force-renderer-accessibility', '--executable-path', browserPath, 'open', 'data:text/html,' + encodeURIComponent(html)], 'open.json');
+  let ownWindow;
+  for (let attempt = 0; attempt < 10 && !ownWindow; attempt++) {
+    const response = JSON.parse(run('agent-desktop', ['list-windows', '--app', application]));
+    assert.equal(response.ok, true);
+    const windows = Array.isArray(response.data) ? response.data : response.data.windows || [];
+    ownWindow = windows.find(window => JSON.stringify(window).includes(title));
+    if (!ownWindow) await new Promise(resolve => setTimeout(resolve, 300));
+  }
+  assert.ok(ownWindow, 'Janela isolada de teste nao encontrada.');
+  const id = ownWindow.id || ownWindow.window_id || ownWindow.windowId;
+  assert.ok(id, 'Identificador da janela ausente.');
+  writeFileSync(join(output, 'window.json'), JSON.stringify(ownWindow, null, 2) + '\n');
+  let result;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    result = JSON.parse(run('agent-desktop', ['snapshot', '--app', application, '--window-id', String(id), '--max-depth', '20', '--timeout-ms', '15000'], 'snapshot.json', true));
+    if (result.ok || result.error?.disposition?.retry !== 'safe') break;
+    await new Promise(resolve => setTimeout(resolve, 300));
+  }
+  assert.equal(result.ok, true);
+  assert.match(JSON.stringify(result.data), /Confirmar teste/);
+  passed = true;
+} finally {
+  run('agent-browser', ['--session', session, 'close'], 'close.json');
+}
+assert.ok(passed);
+console.log('agent-desktop-accessibility=passed; physical-input=none');