@pathbit/agentdevkit 0.0.19 → 0.0.20

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

@@ -49,6 +49,20 @@ export function validateToolConfig(name, value) {
       }
     }
   }
+  if (value.optionalExecutables !== undefined) {
+    if (download.provider !== 'npm' || !value.optionalExecutables || typeof value.optionalExecutables !== 'object' || Array.isArray(value.optionalExecutables) || !Object.keys(value.optionalExecutables).length) fail(`Mapa de executaveis opcionais invalido: ${name}`);
+    for (const [platform, files] of Object.entries(value.optionalExecutables)) {
+      if (!value.platforms.includes(platform) || !Array.isArray(files) || !files.length) fail(`Plataforma de executaveis opcionais invalida: ${name}/${platform}`);
+      const seen = new Set();
+      for (const item of files) {
+        if (!item || typeof item !== 'object' || Array.isArray(item) || Object.keys(item).sort().join(',') !== 'file,package'
+          || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(item.package || '') || seen.has(item.package)
+          || typeof item.file !== 'string' || !item.file || item.file.includes('\0') || item.file.includes('\\') || item.file.includes(':')
+          || item.file.split('/').some(part => !part || part === '.' || part === '..')) fail(`Executavel opcional deve ser relativo ao pacote: ${name}`);
+        seen.add(item.package);
+      }
+    }
+  }
   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();
@@ -162,7 +176,7 @@ export function binaryInvocation(prefix, name, args = [], binaryName = name.spli
   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));
+  const resolved = relative(realpathSync(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); }
@@ -203,25 +217,57 @@ function execute(prefix, entry, args, capture = false, input, environment, runti
   return result.status ?? 1;
 }
 
-function prepareExecutables(prefix, entry, platform) {
-  const files = entry.executables?.[platform];
-  if (!files || process.platform === 'win32') return;
+async function prepareExecutables(prefix, entry, platform, pkg, lock, fetchOptional) {
+  const files = entry.executables?.[platform] || [];
+  const optional = entry.optionalExecutables?.[platform] || [];
+  if (!files.length && !optional.length) 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 declared = optional.filter(item => Object.hasOwn(pkg.optionalDependencies || {}, item.package));
+  const targets = [];
+  const collect = (base, file, label) => {
+    const target = realpathSync(join(base, file));
+    if (!within(base, target)) fail(`Executavel fora do pacote: ${label}`);
     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);
+    if (!info.isFile()) fail(`Executavel nao e arquivo regular: ${label}`);
+    targets.push({ target, mode: (info.mode & 0o777) | 0o111 });
+  };
+  // Older releases contain all of their binaries in the main package. Newer
+  // releases declare a host package; inspect every legacy file that exists so
+  // the upstream launcher cannot prefer an unchecked file over that package.
+  for (const file of files) {
+    let exists = false;
+    try { lstatSync(join(packageRoot, file)); exists = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (exists || !declared.length) collect(packageRoot, file, `${entry.name}/${file}`);
+  }
+  if (declared.length) {
+    let installed = 0;
+    for (const item of declared) {
+      const version = pkg.optionalDependencies[item.package];
+      if (!versionPattern.test(version || '')) fail(`Versao de executavel opcional invalida: ${item.package}`);
+      const directory = sourcePath(prefix, join('node_modules', item.package));
+      try { lstatSync(directory); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+      const optionalRoot = realpathSync(directory);
+      if (!within(realpathSync(join(prefix, 'node_modules')), optionalRoot)) fail(`Pacote opcional fora de node_modules: ${item.package}`);
+      const manifest = json(join(optionalRoot, 'package.json'));
+      const record = lock.packages?.[`node_modules/${item.package}`];
+      const official = await fetchOptional(item.package, version);
+      const tarball = new URL(official.dist?.tarball);
+      if (official.name !== item.package || official.version !== version || tarball.origin !== registry.slice(0, -1)
+        || !decodeURIComponent(tarball.pathname).startsWith(`/${item.package}/-/`) || tarball.search || tarball.hash
+        || !official.dist?.integrity?.startsWith('sha512-') || manifest.name !== item.package || manifest.version !== version
+        || record?.version !== version || record.integrity !== official.dist.integrity || record.resolved !== official.dist.tarball) fail(`Pacote opcional instalado nao corresponde ao registro oficial: ${item.package}`);
+      collect(optionalRoot, item.file, `${item.package}/${item.file}`); installed++;
+    }
+    if (!installed) fail(`Executavel opcional ausente para ${entry.name}/${platform}; instale as dependencias opcionais.`);
+  }
+  if (process.platform !== 'win32') 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 } = {}) {
+  constructor({ root = projectRoot, catalog, fetchRelease, fetchOptional, 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);
@@ -232,11 +278,19 @@ export class ToolManager {
       if (!response.ok) fail(`Registro indisponivel: HTTP ${response.status}`);
       return response.json();
     });
+    this.fetchOptional = fetchOptional || (async (name, version) => {
+      const response = await fetch(`${registry}${encodeURIComponent(name)}/${version}`, { signal: AbortSignal.timeout(20000) });
+      if (!response.ok) fail(`Registro indisponivel para ${name}: HTTP ${response.status}`);
+      return response.json();
+    });
     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,
+      // npm resolves cwd but not --prefix, yielding invalid lock paths when
+      // ancestors are aliases such as macOS /var -> /private/var.
+      const npmPrefix = realpathSync(storagePath(this.root, prefix, 'directory'));
+      const result = spawnSync(runtime.file, [this.npm(runtime, environment), 'install', '--prefix', npmPrefix, '--cache', join(this.home, '.cache/npm'), '--registry', entry.download.registry, '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--save-exact', `${packageName}@${version}`], {
+        cwd: npmPrefix, 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);
@@ -438,7 +492,7 @@ export class ToolManager {
       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);
+        await prepareExecutables(stage, entry, this.target, pkg, lock, this.fetchOptional);
       }
       execute(stage, entry, entry.probe, true, entry.probeInput, toolEnvironment(entry, local, runtime), runtime);
       this.storage(name); storagePath(this.root, target, 'directory');

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

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, readdirSync, existsSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, statSync, renameSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, readdirSync, existsSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, statSync, renameSync, realpathSync } from 'node:fs';
 import { resolve, join, dirname, delimiter } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
@@ -519,6 +519,26 @@ writeFileSync(join(prefix, 'npm-proof.json'), JSON.stringify({args,path:process.
   assert.equal(JSON.parse(readFileSync(join(local, 'CURRENT.json'), 'utf8')).nodePath, process.execPath);
 });
 
+test('npm recebe staging canonico quando a raiz usa alias simbolico', async t => {
+  const config = tool(); const { root } = fixture(t, { 'test-tool': config });
+  const alias = join(root, 'project-alias');
+  if (!createSymlink(t, root, alias, 'dir')) return;
+  const npm = join(root, 'fake-npm.cjs');
+  writeFileSync(npm, `const { mkdirSync, writeFileSync, realpathSync } = require('node:fs');
+const { join } = require('node:path');
+${packageFiles.toString()}
+const prefix = process.argv[process.argv.indexOf('--prefix') + 1];
+if (prefix !== realpathSync(prefix) || process.cwd() !== prefix) process.exit(91);
+packageFiles(prefix, 'test-tool', '1.0.0');
+writeFileSync(join(prefix, 'canonical-proof.json'), JSON.stringify({prefix,cwd:process.cwd()}));
+`);
+  const manager = new ToolManager({ root: alias, catalog: { 'test-tool': config }, npm: () => npm, fetchRelease: async () => release('1.0.0') });
+  const installed = await manager.install('test-tool');
+  const proof = JSON.parse(readFileSync(join(installed.prefix, 'canonical-proof.json'), 'utf8'));
+  assert.equal(proof.cwd, proof.prefix); assert.ok(proof.prefix.startsWith(realpathSync(root)));
+  assert.equal(manager.check('test-tool').version, '1.0.0');
+});
+
 test('setup padrao prepara todas as ferramentas compativeis e confirma cada instalacao', async t => {
   const unsupported = { ...tool('unsupported-tool'), platforms: [process.platform === 'darwin' ? 'linux-x64' : 'darwin-arm64'] };
   const { root, manager, state, local } = fixture(t, { 'test-tool': tool(), 'unsupported-tool': unsupported });
@@ -599,6 +619,62 @@ test('executables valida plataforma e caminhos relativos sem autorizar comandos
   }
 });
 
+test('executaveis opcionais validam pacotes e caminhos sem permitir escapes', () => {
+  const target = platformKey(); const base = tool();
+  const good = { [target]: [{ package: '@owner/cli-host', file: 'bin/probe' }] };
+  assert.deepEqual(validateToolConfig('test-tool', { ...base, optionalExecutables: good }).optionalExecutables, good);
+  for (const item of [
+    { package: '../outside', file: 'bin/probe' }, { package: '@owner/cli-host', file: '../outside' },
+    { package: '@owner/cli-host', file: '/absolute' }, { package: '@owner/cli-host', file: 'C:\\outside' },
+    { package: '@owner/cli-host', file: 'bin/probe', extra: true }
+  ]) assert.throws(() => validateToolConfig('test-tool', { ...base, optionalExecutables: { [target]: [item] } }), /opcional|relativo/);
+  assert.throws(() => validateToolConfig('test-tool', { ...base, optionalExecutables: { [target]: [good[target][0], good[target][0]] } }), /relativo/);
+});
+
+test('atualizacao aceita layout opcional e preserva versao anterior se dependencia falhar', async t => {
+  const targets = process.platform === 'win32' ? [platformKey()] : [platformKey(), 'win32-x64'];
+  for (const target of targets) await t.test(target, async subtest => {
+    const name = '@owner/cli-host'; const isWindowsTarget = target.startsWith('win32-');
+    const config = { ...tool(), platforms: [target], ...(!isWindowsTarget ? { executables: { [target]: ['bin/legacy'] } } : {}), optionalExecutables: { [target]: [{ package: name, file: 'bin/probe' }] } };
+    const [platform, arch] = target.split('-');
+    const { manager, state, local, root } = fixture(subtest, { 'test-tool': config }, { platform, arch });
+    let scenario = 'legacy'; const outside = join(root, 'outside-native'); const probe = join(root, 'probe-executado'); writeFileSync(outside, 'untouched'); chmodSync(outside, 0o644);
+    const officialTarball = version => `https://registry.npmjs.org/${name}/-/cli-host-${version}.tgz`;
+    manager.fetchOptional = async (pkgName, version) => ({ name: pkgName, version, dist: { tarball: officialTarball(version), integrity: 'sha512-fixture' } });
+    manager.installPackage = (prefix, pkgName, version) => {
+      packageFiles(prefix, pkgName, version);
+      const base = join(prefix, 'node_modules', pkgName); mkdirSync(join(base, 'bin'));
+      if (scenario === 'legacy') { writeFileSync(join(base, 'bin/legacy'), 'legacy'); return; }
+      const manifestFile = join(base, 'package.json'); const manifest = JSON.parse(readFileSync(manifestFile));
+      manifest.optionalDependencies = { [name]: version }; writeFileSync(manifestFile, JSON.stringify(manifest));
+      writeFileSync(join(base, 'cli.cjs'), `require('node:fs').writeFileSync(${JSON.stringify(probe)}, 'executado'); console.log(${JSON.stringify(version)});`);
+      if (scenario === 'missing') return;
+      const optional = join(prefix, 'node_modules', name);
+      if (scenario === 'package-link') { mkdirSync(dirname(optional), { recursive: true }); symlinkSync(root, optional, 'dir'); return; }
+      mkdirSync(join(optional, 'bin'), { recursive: true });
+      writeFileSync(join(optional, 'package.json'), JSON.stringify({ name, version: scenario === 'version' ? '9.9.9' : version }));
+      const lockFile = join(prefix, 'package-lock.json'); const lock = JSON.parse(readFileSync(lockFile));
+      lock.packages[`node_modules/${name}`] = { version, integrity: scenario === 'integrity' ? 'sha512-other-registry' : 'sha512-fixture', resolved: scenario === 'registry' ? `https://example.invalid/${name}/-/cli-host-${version}.tgz` : officialTarball(version) };
+      writeFileSync(lockFile, JSON.stringify(lock));
+      if (scenario === 'escape') symlinkSync(outside, join(optional, 'bin/probe'));
+      else { writeFileSync(join(optional, 'bin/probe'), 'probe'); chmodSync(join(optional, 'bin/probe'), 0o644); }
+      if (scenario === 'legacy-escape') symlinkSync(outside, join(base, 'bin/legacy'));
+    };
+    await manager.install('test-tool'); const before = readFileSync(join(local, 'CURRENT.json'), 'utf8'); state.version = '2.0.0';
+    for (scenario of ['missing', 'version', 'integrity', 'registry', ...(process.platform === 'win32' ? [] : ['escape', 'package-link', ...(!isWindowsTarget ? ['legacy-escape'] : [])])]) {
+      await assert.rejects(manager.update('test-tool'), /ausente|corresponde|fora do pacote|nao pode ser um link/);
+      assert.equal(readFileSync(join(local, 'CURRENT.json'), 'utf8'), before);
+      assert.equal(manager.check('test-tool').version, '1.0.0');
+      assert.equal(existsSync(probe), false);
+      assert.ok(readdirSync(local).every(entry => !entry.startsWith('.stage-')));
+    }
+    if (process.platform !== 'win32') assert.equal(statSync(outside).mode & 0o777, 0o644);
+    scenario = 'optional'; const updated = await manager.update('test-tool');
+    assert.equal(updated.version, '2.0.0'); assert.equal(manager.check('test-tool').version, '2.0.0');
+    if (process.platform !== 'win32') assert.equal(statSync(join(updated.prefix, 'node_modules', name, 'bin/probe')).mode & 0o777, 0o755);
+  });
+});
+
 test('executables prepara somente binarios da plataforma no staging antes de executar probe real', { skip: process.platform === 'win32' }, async t => {
   const other = process.platform === 'darwin' ? 'linux-x64' : 'darwin-arm64';
   const config = { ...tool(), platforms: [platformKey(), other], executables: { [platformKey()]: ['native/probe with space'], [other]: ['native/unused'] } };

package/.pbai4devs/tools/agent-browser/TOOL.json

@@ -24,6 +24,14 @@
     "linux-arm64": ["bin/agent-browser-linux-arm64", "bin/agent-browser-linux-musl-arm64"],
     "linux-x64": ["bin/agent-browser-linux-x64", "bin/agent-browser-linux-musl-x64"]
   },
+  "optionalExecutables": {
+    "darwin-arm64": [{"package": "@agent-browser/cli-darwin-arm64", "file": "bin/agent-browser"}],
+    "darwin-x64": [{"package": "@agent-browser/cli-darwin-x64", "file": "bin/agent-browser"}],
+    "linux-arm64": [{"package": "@agent-browser/cli-linux-arm64-gnu", "file": "bin/agent-browser"}, {"package": "@agent-browser/cli-linux-arm64-musl", "file": "bin/agent-browser"}],
+    "linux-x64": [{"package": "@agent-browser/cli-linux-x64-gnu", "file": "bin/agent-browser"}, {"package": "@agent-browser/cli-linux-x64-musl", "file": "bin/agent-browser"}],
+    "win32-arm64": [{"package": "@agent-browser/cli-win32-x64-msvc", "file": "bin/agent-browser.exe"}],
+    "win32-x64": [{"package": "@agent-browser/cli-win32-x64-msvc", "file": "bin/agent-browser.exe"}]
+  },
   "scripts": {
     "entry": "SCRIPT.mjs"
   },

package/CHANGELOG.md

@@ -4,6 +4,11 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.20 — 2026-11-13
+
+- Atualização da ferramenta agent-browser compatível com sua distribuição atual.
+- Orientações para consultar e recuperar versões pelas tags publicadas.
+
 ## 0.0.19 — 2026-11-13
 
 - Pastas dos clientes são ignoradas localmente por padrão, com exceções do projeto.

package/docs/maintainers/maintenance.md

@@ -85,6 +85,28 @@ Também envia o mesmo pacote ao [npm público e GitHub Packages](packages.md),
 confere a integridade nos dois destinos e testa versão, instalação, diagnóstico
 e sincronização. O consumo pelo npm é anônimo; pelo GitHub, autenticado.
 
+A tag é a origem da publicação: `v0.0.19`, a release `v0.0.19` e os pacotes
+`0.0.19` apontam para a mesma entrega. A execução manual também exige a tag;
+não crie outra tag para uma versão nem mova uma tag já publicada.
+
+Para consultar o código de uma versão sem trocar os arquivos atuais:
+
+```console
+git fetch --tags
+git worktree add --detach ../AgentDevKit-v0.0.19 v0.0.19
+```
+
+Em um projeto atendido, fixe a versão desejada do pacote e revise o plano antes
+de aplicá-la:
+
+```console
+npx @pathbit/agentdevkit@0.0.19 update --dry-run --json
+```
+
+O comando usa aquela versão do kit; não reverte automaticamente o histórico
+Git nem arquivos próprios do projeto. Confira os conflitos e faça backup antes
+de aplicar uma versão anterior.
+
 Se o artifact expirou ou um job do CI falhou, use **Re-run all jobs** no CI
 original do push e aguarde todos os jobs. **Re-run failed jobs** pode manter o
 pacote de uma tentativa anterior, que a release não aceita. Depois reexecute

package/docs/specs/README.md

@@ -26,6 +26,7 @@ description: Incrementos verificáveis do AgentDevKit.
 - [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
 - [Ignore do projeto](project-ignore/SPEC.md): preservar o arquivo da raiz.
 - [Ignore de clientes](client-ignore/SPEC.md): padrão local e exceções do projeto.
+- [Ferramenta e versões](tool-release/SPEC.md): atualização segura e tags de release.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/tool-release/SPEC.md

@@ -0,0 +1,19 @@
+---
+description: Atualização segura do agent-browser e recuperação por versão.
+---
+
+# Atualização de ferramenta e versões
+
+O agent-browser passou a distribuir executáveis em pacotes opcionais por
+plataforma. A atualização deve funcionar sem perder instalações existentes.
+
+## Critérios de aceite
+
+- AC-001: O instalador aceita os layouts anterior e atual do agent-browser,
+  valida executáveis adequados à plataforma e comprova a versão instalada.
+- AC-002: Caminhos inválidos ou incompletos são recusados antes da troca;
+  falhas preservam a instalação anterior e não atravessam links inseguros.
+- AC-003: Cada release e pacote do fluxo aponta para a tag da mesma versão;
+  a documentação explica como consultar uma versão e simular seu uso.
+- AC-004: Testes automatizados cobrem layouts e falhas, e a CI verifica Linux,
+  Windows e macOS na matriz configurada antes da publicação.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",