@pathbit/agentdevkit 0.0.10 → 0.0.12

package/.pbai4devs/scripts/lib/managed-toml.mjs

@@ -0,0 +1,192 @@
+import { extractManagedBlock, managedBlockDigest, managedText, mergeManagedContent, stripManagedContent } from './managed-content.mjs';
+
+// Localized editing of Gemini's root prompt; not a general TOML serializer.
+const fail = message => { throw Object.assign(new Error(message), { code: 'E_MANAGED_BLOCK' }); };
+const horizontal = character => character === ' ' || character === '\t';
+const whitespace = character => horizontal(character) || character === '\n' || character === '\r';
+const escapes = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+
+function scalar(code) {
+  if (code > 0x10ffff || code >= 0xd800 && code <= 0xdfff) fail('Escape Unicode TOML invalido.');
+  return String.fromCodePoint(code);
+}
+
+function stringAt(text, start, key = false) {
+  const quote = text[start];
+  if (!['"', "'"].includes(quote)) fail('O prompt TOML deve ser uma string.');
+  const multiline = text.slice(start, start + 3) === quote.repeat(3);
+  if (key && multiline) fail('Chave TOML multiline nao suportada.');
+  const basic = quote === '"';
+  let position = start + (multiline ? 3 : 1), value = '';
+  if (multiline) {
+    if (text.slice(position, position + 2) === '\r\n') position += 2;
+    else if (text[position] === '\n') position++;
+  }
+  while (position < text.length) {
+    const character = text[position];
+    if (character === quote) {
+      if (!multiline) return { start, end: position + 1, value };
+      let count = 1;
+      while (text[position + count] === quote) count++;
+      if (count >= 3) {
+        if (count > 5) fail('Delimitador TOML ambiguo.');
+        return { start, end: position + count, value: value + quote.repeat(count - 3) };
+      }
+      value += quote.repeat(count); position += count; continue;
+    }
+    if (basic && character === '\\') {
+      const escaped = text[++position];
+      if (multiline && whitespace(escaped)) {
+        let cursor = position, lineBreak = false;
+        while (whitespace(text[cursor])) {
+          if (text[cursor] === '\r') {
+            if (text[cursor + 1] !== '\n') fail('TOML exige LF ou CRLF.');
+            lineBreak = true; cursor += 2;
+          } else { if (text[cursor] === '\n') lineBreak = true; cursor++; }
+        }
+        if (!lineBreak) fail('Continuacao de string TOML invalida.');
+        position = cursor; continue;
+      }
+      if (Object.hasOwn(escapes, escaped)) { value += escapes[escaped]; position++; continue; }
+      if (escaped === 'u' || escaped === 'U') {
+        const width = escaped === 'u' ? 4 : 8, digits = text.slice(position + 1, position + 1 + width);
+        if (!new RegExp(`^[0-9a-fA-F]{${width}}$`).test(digits)) fail('Escape Unicode TOML invalido.');
+        value += scalar(Number.parseInt(digits, 16)); position += width + 1; continue;
+      }
+      fail('Escape TOML nao suportado.');
+    }
+    const code = text.charCodeAt(position);
+    if (code === 0x7f || code < 0x20 && character !== '\t' && !(multiline && ['\r', '\n'].includes(character))) fail('Controle invalido em string TOML.');
+    if (!multiline && ['\r', '\n'].includes(character)) fail('String TOML de uma linha interrompida.');
+    if (character === '\r' && text[position + 1] !== '\n') fail('TOML exige LF ou CRLF.');
+    value += character; position++;
+  }
+  fail('String TOML sem fechamento.');
+}
+
+function keyAt(text, start) {
+  let position = start;
+  const path = [];
+  while (true) {
+    while (horizontal(text[position])) position++;
+    if (['"', "'"].includes(text[position])) {
+      const part = stringAt(text, position, true); path.push(part.value); position = part.end;
+    } else {
+      const part = /^[A-Za-z0-9_-]+/.exec(text.slice(position));
+      if (!part) fail('Chave TOML nao suportada.');
+      path.push(part[0]); position += part[0].length;
+    }
+    while (horizontal(text[position])) position++;
+    if (text[position] !== '.') break;
+    position++;
+  }
+  return { path, end: position };
+}
+
+function valueEnd(text, start) {
+  if (['"', "'"].includes(text[start])) return stringAt(text, start).end;
+  const stack = [];
+  let position = start;
+  while (position < text.length) {
+    const character = text[position];
+    if (['"', "'"].includes(character)) { position = stringAt(text, position).end; continue; }
+    if (character === '#') {
+      if (!stack.length) break;
+      while (position < text.length && !['\r', '\n'].includes(text[position])) position++;
+      continue;
+    }
+    if (['\n', '\r'].includes(character) && !stack.length) break;
+    if (character === '[' || character === '{') stack.push(character);
+    if (character === ']' || character === '}') {
+      if (stack.pop() !== (character === ']' ? '[' : '{')) fail('Valor TOML desbalanceado.');
+    }
+    position++;
+  }
+  if (stack.length || !text.slice(start, position).trim()) fail('Valor TOML incompleto.');
+  return position;
+}
+
+function statementEnd(text, start) {
+  let position = start;
+  while (horizontal(text[position])) position++;
+  if (text[position] === '#') while (position < text.length && !['\r', '\n'].includes(text[position])) position++;
+  if (position < text.length && !['\r', '\n'].includes(text[position])) fail('Texto inesperado apos valor TOML.');
+  if (text[position] === '\r') {
+    if (text[position + 1] !== '\n') fail('TOML exige LF ou CRLF.');
+    return position + 2;
+  }
+  return text[position] === '\n' ? position + 1 : position;
+}
+
+function locatePrompt(input) {
+  let text;
+  try { text = managedText(input); }
+  catch (error) {
+    if (error.code === 'E_MANAGED_BLOCK') throw error;
+    fail('Texto TOML deve ser UTF-8 valido.');
+  }
+  for (const character of text) {
+    const code = character.codePointAt(0);
+    if (code >= 0xd800 && code <= 0xdfff) fail('Unicode TOML invalido.');
+  }
+  let position = text.startsWith('\ufeff') ? 1 : 0, root = true, insertion = text.length, prompt = null, reserved = false;
+  while (position < text.length) {
+    const lineStart = position;
+    while (horizontal(text[position])) position++;
+    if (position === text.length) break;
+    if (text[position] === '#' || ['\r', '\n'].includes(text[position])) { position = statementEnd(text, position); continue; }
+    if (text[position] === '[') {
+      const arrayTable = text[position + 1] === '[';
+      const header = keyAt(text, position + (arrayTable ? 2 : 1));
+      if (text.slice(header.end, header.end + (arrayTable ? 2 : 1)) !== (arrayTable ? ']]' : ']')) fail('Tabela TOML invalida.');
+      if (root) insertion = lineStart;
+      root = false;
+      if (header.path[0] === 'prompt') reserved = true;
+      position = statementEnd(text, header.end + (arrayTable ? 2 : 1)); continue;
+    }
+    const key = keyAt(text, position);
+    if (text[key.end] !== '=') fail('Atribuicao TOML invalida.');
+    position = key.end + 1;
+    while (horizontal(text[position])) position++;
+    if (root && key.path[0] === 'prompt') {
+      if (key.path.length !== 1 || prompt || reserved) fail('Prompt TOML duplicado ou ambiguo.');
+      prompt = stringAt(text, position);
+      position = prompt.end;
+    } else position = valueEnd(text, position);
+    position = statementEnd(text, position);
+  }
+  if (reserved) fail('Prompt TOML ocupa uma tabela; conteudo preservado.');
+  return { text, prompt, insertion };
+}
+
+function encode(value) {
+  return JSON.stringify(value).replace(/\x7f/g, '\\u007F');
+}
+
+export function extractTomlManagedBlock(input) {
+  const { prompt } = locatePrompt(input);
+  return prompt ? extractManagedBlock(prompt.value) : null;
+}
+
+export function tomlManagedBlockDigest(input) {
+  const { prompt } = locatePrompt(input);
+  return prompt ? managedBlockDigest(prompt.value) : null;
+}
+
+export function mergeTomlContent(input, body, options = {}) {
+  const { text, prompt, insertion } = locatePrompt(input);
+  const result = mergeManagedContent(prompt?.value ?? '', body, options);
+  if (prompt && !result.changed) return { ...result, text, changed: false };
+  const eol = text.match(/\r\n|\n/)?.[0] || '\n';
+  const separator = insertion && !/[\r\n]$/.test(text.slice(0, insertion)) ? eol : '';
+  const content = prompt ? text.slice(0, prompt.start) + encode(result.text) + text.slice(prompt.end)
+    : text.slice(0, insertion) + separator + `prompt = ${encode(result.text)}${eol}` + text.slice(insertion);
+  return { ...result, text: content, changed: content !== text };
+}
+
+export function stripTomlContent(input, expectedHash) {
+  const { text, prompt } = locatePrompt(input);
+  if (!prompt) return text;
+  const stripped = stripManagedContent(prompt.value, expectedHash);
+  return stripped === prompt.value ? text : text.slice(0, prompt.start) + encode(stripped) + text.slice(prompt.end);
+}

package/.pbai4devs/scripts/lib/native-release.mjs

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { gunzipSync, inflateRawSync } from 'node:zlib';
+
+const limit = 256 * 1024 * 1024;
+const hosts = new Set(['github.com', 'release-assets.githubusercontent.com', 'objects.githubusercontent.com', 'github-releases.githubusercontent.com']);
+const fail = message => { throw new Error(message); };
+export const nativeHash = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function safeName(value, directory = false) {
+  if (typeof value !== 'string' || !value || /[\\\x00-\x1f:]/.test(value) || isAbsolute(value)) fail('Caminho invalido no arquivo nativo.');
+  const normalized = directory ? value.replace(/\/$/, '') : value;
+  if (!normalized || normalized.split('/').some(part => !part || part === '.' || part === '..')) fail('Caminho invalido no arquivo nativo.');
+  return normalized;
+}
+
+export function validateNativeDownload(download, platforms) {
+  if (download?.provider !== 'github-release' || download.channel !== 'reviewed'
+    || !/^[A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*$/.test(download.repository || '')
+    || !/^\d+\.\d+\.\d+$/.test(download.version || '') || download.tag !== `v${download.version}`) fail('Release nativa deve usar origem e versao revisadas.');
+  if (!download.assets || typeof download.assets !== 'object' || Array.isArray(download.assets)
+    || Object.keys(download.assets).length !== platforms.length) fail('Assets nativos devem corresponder as plataformas.');
+  for (const platform of platforms) {
+    const asset = download.assets[platform];
+    if (!Object.hasOwn(download.assets, platform) || !asset || typeof asset !== 'object' || !['raw', 'tar.gz', 'zip'].includes(asset.format)
+      || !/^[a-f0-9]{64}$/.test(asset.sha256 || '') || !/^\w[\w.-]*$/.test(asset.file || '')) fail(`Asset nativo invalido: ${platform}`);
+    safeName(asset.binary);
+  }
+  return download;
+}
+
+export function nativeRelease(entry, platform) {
+  validateNativeDownload(entry.download, entry.platforms);
+  const asset = entry.download.assets[platform];
+  if (!asset) fail(`Plataforma nativa nao suportada: ${platform}`);
+  const { repository, version, tag } = entry.download;
+  return { name: entry.name, version, repository, platform, asset: { ...asset },
+    url: `https://github.com/${repository}/releases/download/${tag}/${asset.file}` };
+}
+
+export function validateNativeRelease(entry, release, platform) {
+  const expected = nativeRelease(entry, platform);
+  if (!release || JSON.stringify(release) !== JSON.stringify(expected)) fail('Release nativa diverge do pin revisado.');
+  return release;
+}
+
+export async function downloadNative(url, { fetcher = fetch, maxBytes = limit, timeoutMs = 60000 } = {}) {
+  let current = new URL(url);
+  if (current.hostname !== 'github.com') fail('Download nativo deve iniciar no GitHub oficial.');
+  for (let redirects = 0; redirects <= 5; redirects++) {
+    if (current.protocol !== 'https:' || current.username || current.password || !hosts.has(current.hostname)) fail('Host de download nativo nao permitido.');
+    const response = await fetcher(current.href, { redirect: 'manual', headers: { Accept: 'application/octet-stream' }, signal: AbortSignal.timeout(timeoutMs) });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers.get('location');
+      if (!location || redirects === 5) fail('Redirecionamento nativo invalido.');
+      current = new URL(location, current);
+      await response.body?.cancel();
+      continue;
+    }
+    if (!response.ok) fail(`Download nativo falhou: HTTP ${response.status}.`);
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) fail('Download nativo excede o limite.');
+    const chunks = []; let size = 0;
+    for await (const chunk of response.body) {
+      size += chunk.byteLength;
+      if (size > maxBytes) fail('Download nativo excede o limite.');
+      chunks.push(Buffer.from(chunk));
+    }
+    if (!size) fail('Download nativo vazio.');
+    return Buffer.concat(chunks, size);
+  }
+  fail('Redirecionamentos nativos excedidos.');
+}
+
+function tarBytes(archive, binary) {
+  const data = gunzipSync(archive, { maxOutputLength: limit });
+  const names = new Set(); let selected, ended = false;
+  for (let offset = 0; offset + 512 <= data.length;) {
+    const header = data.subarray(offset, offset + 512);
+    if (header.every(value => value === 0)) {
+      if (data.length - offset < 1024 || !data.subarray(offset).every(value => value === 0)) fail('Final tar invalido.');
+      ended = true; break;
+    }
+    const text = (start, length) => header.subarray(start, start + length).toString('utf8').split('\0')[0];
+    const number = (start, length) => { const value = text(start, length).trim(); if (!/^[0-7]+$/.test(value)) fail('Cabecalho tar invalido.'); return parseInt(value, 8); };
+    const checksum = [...header].reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+    if (number(148, 8) !== checksum) fail('Checksum do cabecalho tar invalido.');
+    const type = String.fromCharCode(header[156]), directory = type === '5';
+    if (!['0', '\0', '5'].includes(type)) fail('Links ou entradas especiais nao permitidos no tar.');
+    const name = safeName([text(345, 155), text(0, 100)].filter(Boolean).join('/'), directory);
+    const key = name.toLowerCase(); if (names.has(key)) fail('Entrada duplicada no tar.'); names.add(key);
+    const size = number(124, 12); offset += 512;
+    if (size > limit || offset + size > data.length || directory && size) fail('Tamanho tar invalido.');
+    if (!directory && name === binary) selected = Buffer.from(data.subarray(offset, offset + size));
+    offset += Math.ceil(size / 512) * 512;
+  }
+  if (!ended) fail('Arquivo tar incompleto.');
+  if (!selected?.length) fail('Executavel esperado ausente no tar.');
+  return selected;
+}
+
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) { crc ^= byte; for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1)); }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function zipBytes(data, binary) {
+  let end = -1;
+  for (let offset = data.length - 22; offset >= Math.max(0, data.length - 65557); offset--) {
+    if (data.readUInt32LE(offset) === 0x06054b50 && offset + 22 + data.readUInt16LE(offset + 20) === data.length) { end = offset; break; }
+  }
+  if (end < 0 || data.readUInt16LE(end + 4) || data.readUInt16LE(end + 6)) fail('Arquivo ZIP invalido ou multipartes.');
+  const count = data.readUInt16LE(end + 10), centralSize = data.readUInt32LE(end + 12), central = data.readUInt32LE(end + 16);
+  if (count === 0xffff || count !== data.readUInt16LE(end + 8) || central + centralSize !== end) fail('Diretorio ZIP invalido ou ZIP64.');
+  const names = new Set(); let selected, offset = central;
+  for (let index = 0; index < count; index++) {
+    if (offset + 46 > end || data.readUInt32LE(offset) !== 0x02014b50) fail('Entrada ZIP invalida.');
+    const flags = data.readUInt16LE(offset + 8), method = data.readUInt16LE(offset + 10), crc = data.readUInt32LE(offset + 16);
+    const compressed = data.readUInt32LE(offset + 20), size = data.readUInt32LE(offset + 24);
+    const nameLength = data.readUInt16LE(offset + 28), extra = data.readUInt16LE(offset + 30), comment = data.readUInt16LE(offset + 32);
+    const disk = data.readUInt16LE(offset + 34), attributes = data.readUInt32LE(offset + 38), local = data.readUInt32LE(offset + 42);
+    if (offset + 46 + nameLength + extra + comment > end || flags & 1 || disk || ![0, 8].includes(method) || size > limit || compressed > limit) fail('Formato ZIP nao permitido.');
+    const original = data.subarray(offset + 46, offset + 46 + nameLength).toString('utf8');
+    const directory = original.endsWith('/'), name = safeName(original, directory), mode = attributes >>> 16, type = mode & 0o170000;
+    if (![0, 0o100000, 0o040000].includes(type) || type === 0o040000 && !directory) fail('Link ou entrada especial no ZIP.');
+    const key = name.toLowerCase(); if (names.has(key)) fail('Entrada duplicada no ZIP.'); names.add(key);
+    if (local + 30 > central || data.readUInt32LE(local) !== 0x04034b50 || data.readUInt16LE(local + 6) !== flags || data.readUInt16LE(local + 8) !== method) fail('Cabecalho local ZIP divergente.');
+    const localNameLength = data.readUInt16LE(local + 26), localExtra = data.readUInt16LE(local + 28), start = local + 30 + localNameLength + localExtra;
+    if (start + compressed > central || data.subarray(local + 30, local + 30 + localNameLength).toString('utf8') !== original) fail('Caminho local ZIP divergente.');
+    if (!directory && name === binary) {
+      const packed = data.subarray(start, start + compressed);
+      selected = method === 0 ? Buffer.from(packed) : inflateRawSync(packed, { maxOutputLength: limit });
+      if (selected.length !== size || crc32(selected) !== crc) fail('Integridade do executavel ZIP invalida.');
+    }
+    offset += 46 + nameLength + extra + comment;
+  }
+  if (offset !== end || !selected?.length) fail('Executavel esperado ausente no ZIP.');
+  return selected;
+}
+
+export function extractNative(archive, asset) {
+  if (!Buffer.isBuffer(archive) || !archive.length || archive.length > limit) fail('Tamanho de arquivo nativo invalido.');
+  safeName(asset.binary);
+  if (nativeHash(archive) !== asset.sha256) fail('SHA-256 do download nativo diverge do pin revisado.');
+  if (asset.format === 'raw') return archive;
+  if (asset.format === 'tar.gz') return tarBytes(archive, asset.binary);
+  if (asset.format === 'zip') return zipBytes(archive, asset.binary);
+  fail('Formato nativo nao suportado.');
+}
+
+function checkedFile(prefix, relativePath) {
+  safeName(relativePath);
+  const base = resolve(prefix), file = resolve(base, relativePath), child = relative(base, file);
+  if (isAbsolute(child) || child === '..' || child.startsWith(`..${sep}`)) fail('Executavel fora da instalacao.');
+  if (!lstatSync(base).isDirectory() || lstatSync(base).isSymbolicLink()) fail('Raiz nativa deve ser um diretorio regular.');
+  let current = base;
+  for (const segment of child.split(sep)) {
+    current = join(current, segment);
+    try { if (lstatSync(current).isSymbolicLink()) fail('Link simbolico na instalacao nativa.'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return file;
+}
+
+export function nativeExecutable(entry, platform) { return `bin/${entry.name}${platform.startsWith('win32-') ? '.exe' : ''}`; }
+
+export async function installNative(prefix, entry, platform, { download = downloadNative } = {}) {
+  const release = nativeRelease(entry, platform), archive = await download(release.url), bytes = extractNative(archive, release.asset);
+  const executable = nativeExecutable(entry, platform), target = checkedFile(prefix, executable);
+  mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, bytes, { flag: 'wx', mode: 0o755 }); chmodSync(target, 0o755);
+  const receipt = { name: entry.name, version: release.version, platform, executable, archiveSha256: release.asset.sha256, binarySha256: nativeHash(bytes) };
+  writeFileSync(checkedFile(prefix, 'native.json'), JSON.stringify(receipt, null, 2) + '\n', { flag: 'wx' });
+  return receipt;
+}
+
+export function checkNative(prefix, entry, platform) {
+  const file = checkedFile(prefix, 'native.json');
+  if (!lstatSync(file).isFile()) fail('Recibo nativo invalido.');
+  const receipt = JSON.parse(readFileSync(file, 'utf8'));
+  const release = nativeRelease(entry, platform);
+  if (receipt.name !== entry.name || receipt.version !== release.version || receipt.platform !== platform
+    || receipt.executable !== nativeExecutable(entry, platform) || receipt.archiveSha256 !== release.asset.sha256
+    || !/^[a-f0-9]{64}$/.test(receipt.binarySha256 || '')) fail('Recibo nativo diverge do catalogo revisado.');
+  const executable = checkedFile(prefix, receipt.executable);
+  if (!lstatSync(executable).isFile() || nativeHash(readFileSync(executable)) !== receipt.binarySha256) fail('Executavel nativo alterado.');
+  return { ...receipt, file: executable };
+}
+
+export function assertNativeVersion(output, version) {
+  if (!new RegExp(`(?:^|[^\\w.])v?${version.replaceAll('.', '\\.')}(?=$|[^\\w.+-])`).test(output)) fail('Probe nativo informou outra versao.');
+}

package/.pbai4devs/scripts/preparar-ferramentas/README.md

@@ -54,14 +54,20 @@ Locks ativos, de outro host ou sem metadados verificáveis são preservados.
 Não aceita grupos. Um lock ausente não cria arquivos.
 
 O requisito comum é Node.js 24+ com npm. O gerenciador usa o Node atual.
-Downloads usam npm oficial com scripts de instalação desativados e integridade
-conferida.
+Pacotes npm usam o registro oficial com scripts de instalação desativados.
+Scanners nativos usam assets oficiais do GitHub com versão e SHA-256 revisados.
+`update` segue `latest` no npm e o pin do catálogo nos scanners nativos.
+Os dois caminhos conferem integridade antes de executar e preservam a versão
+anterior se a atualização falhar.
 Permissões de binários POSIX são aplicadas somente aos caminhos declarados
 em `executables` no `TOOL.json`, antes do probe.
 Atualizações usam staging e preservam a versão anterior em caso de falha.
 Atalhos locais recusam diretórios e arquivos simbólicos antes de escrever.
 O preparo valida os CLIs. Navegador, permissões desktop e FFmpeg dependem da
 tarefa; ele não inicia aplicações nem concede permissões automaticamente.
+No grupo `security`, a base OSV também é separada do CLI. Use o comando
+[preparar-seguranca](../../commands/preparar-seguranca/COMMAND.md) para orientar
+instalação, atualização explícita dos dados e análise offline.
 
 Testes: `node --test .pbai4devs/scripts/preparar-ferramentas/tests/TEST.mjs`.
 Após instalar `skills`, `just-bash`, `opensrc`, `webreel` e `portless`, execute

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

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 import { projectRoot, requireNode, isMain } from '../lib/runtime.mjs';
+import { validateNativeDownload, nativeRelease, validateNativeRelease, installNative, checkNative, assertNativeVersion } from '../lib/native-release.mjs';
 
 const registry = 'https://registry.npmjs.org/';
 const versionPattern = /^\d+\.\d+\.\d+(?:-[\w.-]+)?$/;
@@ -29,9 +30,13 @@ 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 (!['npm', 'github-release'].includes(download?.provider)) fail(`Download nao suportado: ${name}`);
+  if (download.provider === 'npm') {
+    if (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 (download.provider === 'github-release') validateNativeDownload(download, value.platforms);
   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) {
@@ -72,7 +77,7 @@ 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.',
+    update: entry.download.provider === 'github-release' ? 'Aplica a versao revisada do catalogo com rollback.' : '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.',
@@ -128,7 +133,8 @@ export function loadCatalog(root = projectRoot) {
   return catalog;
 }
 
-export function validateRelease(name, entry, release) {
+export function validateRelease(name, entry, release, platform = platformKey()) {
+  if (entry.download.provider === 'github-release') return validateNativeRelease(entry, release, platform);
   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}`);
@@ -165,6 +171,9 @@ export function binaryInvocation(prefix, name, args = [], binaryName = name.spli
 
 export function toolEnvironment(entry, local, runtime) {
   const environment = Object.assign(Object.create(null), process.env);
+  if (entry.download?.provider === 'github-release') {
+    for (const key of Object.keys(environment)) if (/token|secret|password|(?:^|_)auth(?:_|$)|^(?:semgrep|opengrep)_/i.test(key)) delete environment[key];
+  }
   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;
@@ -184,10 +193,13 @@ export function toolEnvironment(entry, local, runtime) {
 }
 
 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 native = entry.download.provider === 'github-release';
+  const [file, options] = native ? [checkNative(prefix, entry, runtime.platform || platformKey()).file, args]
+    : 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);
+  if (capture && native) assertNativeVersion(`${result.stdout || ''}\n${result.stderr || ''}`, entry.download.version);
   return result.status ?? 1;
 }
 
@@ -215,11 +227,13 @@ export class ToolManager {
     this.catalog = catalog ?? loadCatalog(this.root);
     for (const [name, entry] of Object.entries(this.catalog)) validateToolConfig(name, entry);
     this.fetchRelease = fetchRelease || (async (name, entry) => {
+      if (entry.download.provider === 'github-release') return nativeRelease(entry, this.target);
       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) => {
+    this.installPackage = install || (async (prefix, packageName, version, entry, runtime) => {
+      if (entry.download.provider === 'github-release') return installNative(prefix, entry, this.target);
       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,
@@ -236,7 +250,7 @@ export class ToolManager {
     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 };
+    return { file: process.execPath, version: process.version, platform: this.target };
   }
   preflight(names) {
     const issues = [];
@@ -298,8 +312,13 @@ export class ToolManager {
   }
   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}`);
+    if (entry.download.provider === 'github-release') {
+      const receipt = checkNative(info.prefix, entry, this.target);
+      if (receipt.version !== info.version || receipt.binarySha256 !== info.binarySha256) fail(`Versao local divergente: ${name}`);
+    } else {
+      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;
   }
@@ -399,7 +418,7 @@ export class ToolManager {
     renameSync(storagePath(this.root, temporary, 'file'), storagePath(this.root, join(local, 'CURRENT.json'), 'file'));
   }
   async updateLocked(name) {
-    const entry = this.entry(name); const runtime = this.runtime(name); const release = validateRelease(name, entry, await this.fetchRelease(name, entry));
+    const entry = this.entry(name); const runtime = this.runtime(name); const release = validateRelease(name, entry, await this.fetchRelease(name, entry), this.target);
     const { local } = this.storage(name);
     const target = storagePath(this.root, join(local, 'versions', `${release.version}-${this.target}`), 'directory');
     let installed;
@@ -409,14 +428,21 @@ export class ToolManager {
     const stage = mkdtempSync(join(local, '.stage-'));
     const temporary = storagePath(this.root, join(local, `CURRENT.${randomUUID()}.json`), 'file'); let previous; let moved = false;
     try {
-      this.installPackage(stage, entry.download.package, release.version, entry, runtime);
+      if (entry.download.provider === 'github-release') {
+        for (const location of Object.values(entry.envPaths || {})) mkdirSync(storagePath(this.root, join(local, location), 'directory'), { recursive: true });
+      }
+      await this.installPackage(stage, entry.download.package, release.version, entry, runtime);
       this.storage(name); storagePath(this.root, stage, 'directory');
-      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);
+      let receipt;
+      if (entry.download.provider === 'github-release') receipt = checkNative(stage, entry, this.target);
+      else {
+        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);
       this.storage(name); storagePath(this.root, target, 'directory');
-      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() };
+      const info = { name, ...(receipt ? { provider: 'github-release', binarySha256: receipt.binarySha256, archiveSha256: receipt.archiveSha256 } : { package: entry.download.package }), version: release.version, platform: this.target, node: runtime.version, nodePath: runtime.file, source: entry.source, tarball: receipt ? release.url : release.dist.tarball, integrity: receipt ? `sha256-${Buffer.from(receipt.archiveSha256, 'hex').toString('base64')}` : release.dist.integrity, checkedAt: new Date().toISOString() };
       writeFileSync(storagePath(this.root, temporary, 'file'), `${JSON.stringify(info, null, 2)}\n`, { flag: 'wx' });
       this.launchers(name);
       if (existsSync(target)) { previous = storagePath(this.root, `${target}.previous-${randomUUID()}`, 'directory'); renameSync(storagePath(this.root, target, 'directory'), previous); }
@@ -425,7 +451,11 @@ export class ToolManager {
       return { ...info, layout: 'local', prefix: target, changed: true };
     } finally { rmSync(storagePath(this.root, stage, 'directory'), { recursive: true, force: true }); rmSync(storagePath(this.root, temporary, 'file'), { 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); }
+  run(name, args) {
+    const entry = this.entry(name), runtime = this.runtime(name), current = this.current(name);
+    if (entry.download.provider === 'github-release' && checkNative(current.prefix, entry, this.target).binarySha256 !== current.binarySha256) fail(`Recibo local divergente: ${name}`);
+    return execute(current.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].';

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

@@ -8,6 +8,7 @@ import { hostname } from 'node:os';
 import { ToolManager, platformKey, validateRelease, validateToolConfig, loadCatalog, main, toolEnvironment, binaryInvocation, toolActions, toolWrapper } from '../SCRIPT.mjs';
 import { requireNode } from '../../lib/runtime.mjs';
 import './bootstrap.test.mjs';
+import './native-release.test.mjs';
 
 const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
 const tool = (name = 'test-tool', group = 'base') => ({ name, description: 'Ferramenta da fixture.', group, source: `https://github.com/owner/${name}`, download: { provider: 'npm', package: name, registry: 'https://registry.npmjs.org/', repository: `owner/${name}`, channel: 'latest' }, platforms: [platformKey()], scripts: { entry: 'SCRIPT.mjs' }, probe: ['--version'] });
@@ -44,6 +45,7 @@ function fixture(t, catalog = { 'test-tool': tool() }, options = {}) {
   copyFileSync(join(project, '.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs'), join(common, 'SCRIPT.mjs'));
   mkdirSync(join(root, '.pbai4devs/scripts/lib'), { recursive: true });
   copyFileSync(join(project, '.pbai4devs/scripts/lib/runtime.mjs'), join(root, '.pbai4devs/scripts/lib/runtime.mjs'));
+  copyFileSync(join(project, '.pbai4devs/scripts/lib/native-release.mjs'), join(root, '.pbai4devs/scripts/lib/native-release.mjs'));
   const state = { version: '1.0.0', installs: 0, fetches: 0, fail: false, tamper: false, broken: false, noBin: false };
   const manager = new ToolManager({ root, catalog, fetchRelease: async name => { state.fetches++; return release(state.version, name); }, install(prefix, name, version) { state.installs++; if (state.fail) throw new Error('download de prova falhou'); packageFiles(prefix, name, version, state); }, ...options });
   return { root, manager, state, local: join(root, '.pbai4devs/tools/test-tool/.local') };