@pathbit/agentdevkit 0.0.27 → 0.0.28

package/.pbai4devs/scripts/README.md

@@ -10,8 +10,9 @@ comando em macOS, Linux e Windows. Bun não faz parte do contrato validado.
 Versione scripts e testes; salve somente resultados em `.agent-tests/`.
 Prepare ferramentas locais com `preparar-ferramentas`, sem instalações globais.
 O runtime da aplicação será decidido no design doc; este requisito é dos agentes.
-Com Node 18+, use o [bootstrap JavaScript](preparar-ferramentas/BOOTSTRAP.md)
-com `--runtime-only` para preparar Node 24+ e continuar a operação.
+Com Node 18+, o [bootstrap JavaScript](preparar-ferramentas/BOOTSTRAP.md)
+prepara Node 24+ com `--runtime-only` ou encadeia preparo, diagnóstico e seleção
+com [`--executar`](executar-script/README.md).
 Sem Node/npm, o agente instala primeiro pelo mecanismo do sistema operacional.
 Não há inicializadores `.sh` ou `.ps1` no kit.
 

package/.pbai4devs/scripts/executar-script/README.md

@@ -7,6 +7,29 @@ description: Executor comum dos scripts Node do projeto.
 Use Node 24+ com o nome de uma pasta em `.pbai4devs/scripts/`, uma pasta do
 repositório ou o caminho de um arquivo `.mjs`. O comando funciona nos três SOs:
 
+```console
+cd .pbai4devs/scripts/preparar-ferramentas
+node BOOTSTRAP.mjs --executar --plan preparar-ferramentas
+node BOOTSTRAP.mjs --executar preparar-ferramentas list
+cd ../../..
+```
+
+`--executar` prepara Node/npm, diagnostica e só então chama o seletor. Falha
+no diagnóstico interrompe a operação, inclusive se houver configuração de
+ferramenta inválida sem relação com o alvo; inspecione a falha. Diagnóstico com
+sucesso indica inventário concluído, não que todas as dependências do alvo estão
+prontas. Com `--no-install`, o bootstrap usa o runtime atual, o primeiro Node
+do PATH ou o cache, desde que compatível, sem baixar ou instalar o runtime.
+Essa opção não restringe rede nem
+instalações pelo diagnóstico ou script filho. O plano também não baixa, instala
+nem diagnostica, e usa as mesmas opções de runtime.
+O alvo, seus argumentos e o código de saída são preservados.
+Na saída padrão, `--executar` reúne o caminho do runtime, o diagnóstico, o
+cabeçalho do seletor e a saída do alvo; ela não é um JSON único nem uma saída
+bruta do alvo. O seletor direto também inclui seu próprio cabeçalho.
+
+Com Node 24+ já disponível, o seletor pode ser chamado diretamente:
+
 ```console
 node .pbai4devs/scripts/executar-script/SCRIPT.mjs --plan preparar-ferramentas
 node .pbai4devs/scripts/executar-script/SCRIPT.mjs preparar-ferramentas list

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

@@ -15,7 +15,10 @@ node .pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs --runtime-only
 ```
 
 O modo `--runtime-only` imprime `node=<caminho absoluto>` sem instalar
-ferramentas. Sem a opção, continua com `setup`; aceita grupo ou nome.
+ferramentas. Sem opções, continua com `setup`; aceita grupo ou nome.
+Para preparar o runtime, diagnosticar e executar um script em sequência, veja
+[`--executar`](../executar-script/README.md). O plano e `--no-install` não
+baixam o runtime; não restringem efeitos dos processos que forem executados.
 
 O fluxo reutiliza um runtime saudável ou o cache local. Se necessário, baixa
 Node 24 de `nodejs.org`, verifica SHA-256 e extrai usando `tar` nativo.

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

@@ -109,7 +109,7 @@ export function validateExtracted(root) {
   visit(base);
 }
 
-export async function ensureRuntime({ root = projectRoot, minimum = 24, node = process.execPath, platform = process.platform, arch = process.arch, libc, run = spawnSync, download = downloadOfficial, environment = process.env } = {}) {
+export async function ensureRuntime({ root = projectRoot, minimum = 24, node = process.execPath, platform = process.platform, arch = process.arch, libc, run = spawnSync, download = downloadOfficial, environment = process.env, allowDownload = true, searchPath = false } = {}) {
   if (Number(process.versions.node.split('.')[0]) < 18) failure('O inicializador requer Node.js 18+; instale Node.js 24+ pelo gerenciador do SO.');
   root = realpathSync(root);
   const current = probe(node, minimum, run, environment);
@@ -117,6 +117,12 @@ export async function ensureRuntime({ root = projectRoot, minimum = 24, node = p
     const npm = npmFor(current.node, run, environment, platform);
     if (npm) return { node: current.node, npm, version: current.version, source: 'current' };
   }
+  if (searchPath) {
+    const executable = findExecutable('node', environment, platform);
+    const found = executable && probe(executable, minimum, run, environment);
+    const npm = found && npmFor(found.node, run, environment, platform);
+    if (found && npm) return { node: found.node, npm, version: found.version, source: 'path' };
+  }
   const targetPlatform = platformName(platform, arch, run, environment, libc);
   const cache = safePath(root, ['.pbai4devs', 'tools', '.cache', 'runtime', 'node', targetPlatform]);
   if (stat(cache) && !stat(cache).isDirectory()) failure('Cache de runtime nao e diretorio.');
@@ -126,6 +132,7 @@ export async function ensureRuntime({ root = projectRoot, minimum = 24, node = p
     const found = probe(executable, minimum, run, environment);
     if (found) { const npm = npmFor(executable, run, environment, platform, true); if (npm) return { node: executable, npm, version: found.version, source: 'cache' }; }
   }
+  if (!allowDownload) failure('Node.js 24+ e npm nao encontrados; prepare o runtime antes de continuar.');
   const tar = findExecutable('tar', environment, platform);
   if (!tar) failure('Instale tar pelo gerenciador do SO para extrair o Node local.');
   mkdirSync(cache, { recursive: true });
@@ -170,11 +177,42 @@ export async function ensureRuntime({ root = projectRoot, minimum = 24, node = p
 
 export async function main(args = process.argv.slice(2), options = {}) {
   const runtimeOnly = args[0] === '--runtime-only';
+  const execute = args[0] === '--executar';
+  const selected = execute ? args.slice(1) : [];
+  let plan = false, noInstall = false;
+  while (execute && ['--plan', '--no-install'].includes(selected[0])) {
+    if (selected[0] === '--plan') { if (plan) failure('--plan duplicado.'); plan = true; }
+    else { if (noInstall) failure('--no-install duplicado.'); noInstall = true; }
+    selected.shift();
+  }
   if (runtimeOnly && args.length !== 1) failure('--runtime-only nao aceita selecao ou outros argumentos.');
-  if (!runtimeOnly && args.some(arg => arg.startsWith('-'))) failure('Use --runtime-only ou uma selecao de ferramentas.');
-  const runtime = await ensureRuntime(options);
+  if (execute && !selected[0]) failure('Use --executar [--no-install] [--plan] <nome-ou-caminho> [argumentos].');
+  if (!runtimeOnly && !execute && args.some(arg => arg.startsWith('-'))) failure('Use --runtime-only ou uma selecao de ferramentas.');
+  if (execute && ['--help', '-h'].includes(selected[0])) {
+    process.stdout.write('Uso: --executar [--no-install] [--plan] <nome-ou-caminho> [argumentos]\n');
+    return 0;
+  }
+  if (execute) {
+    const { resolveScript } = await import('../executar-script/SCRIPT.mjs');
+    resolveScript(selected[0], { root: options.root || projectRoot });
+  }
+  const runtime = await ensureRuntime({ ...options, allowDownload: !plan && !noInstall, searchPath: execute });
   process.stdout.write(`node=${runtime.node}\n`);
   if (runtimeOnly) return 0;
+  if (execute) {
+    const run = options.run || spawnSync;
+    const root = options.root || projectRoot;
+    const env = environmentWithNode(options.environment || process.env, runtime.node);
+    const processOptions = { stdio: 'inherit', env, cwd: root, windowsHide: true };
+    if (!plan) {
+      const diagnostic = run(runtime.node, [join(root, '.pbai4devs/scripts/diagnosticar-ambiente/SCRIPT.mjs')], processOptions);
+      if (diagnostic.error) throw diagnostic.error;
+      if (diagnostic.status !== 0) return diagnostic.status ?? 1;
+    }
+    const result = run(runtime.node, [join(root, '.pbai4devs/scripts/executar-script/SCRIPT.mjs'), ...(plan ? ['--plan'] : []), ...selected], processOptions);
+    if (result.error) throw result.error;
+    return result.status ?? 1;
+  }
   const result = (options.run || spawnSync)(runtime.node, [join(options.root || projectRoot, '.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs'), 'setup', ...args], { stdio: 'inherit', env: environmentWithNode(options.environment || process.env, runtime.node) });
   if (result.error) throw result.error;
   return result.status ?? 1;
@@ -185,5 +223,8 @@ function isEntrypoint() {
   catch { return false; }
 }
 if (isEntrypoint()) {
-  try { process.exitCode = await main(); } catch (error) { console.error(`bootstrap: ${error.message}`); process.exitCode = 1; }
+  try { process.exitCode = await main(); } catch (error) {
+    console.error(`bootstrap: ${error.message}`);
+    process.exitCode = Number.isInteger(error.exitCode) && error.exitCode >= 1 && error.exitCode <= 255 ? error.exitCode : 1;
+  }
 }

package/.pbai4devs/scripts/preparar-ferramentas/tests/bootstrap.test.mjs

@@ -1,8 +1,9 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { createHash } from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { ensureRuntime, main, validateArchive, validateExtracted } from '../BOOTSTRAP.mjs';
@@ -29,7 +30,7 @@ function fixture(t) {
   let manifest = `${checksum}  ${top}.${extension}\n`, calls = 0;
   const run = (file, args, options) => {
     if (args[0] === '-p') {
-      if (!existsSync(file) || readFileSync(file, 'utf8') !== 'fixture-node') return { status: 1, stdout: '' };
+      if (!file.startsWith(root + sep) || !existsSync(file) || readFileSync(file, 'utf8') !== 'fixture-node') return { status: 1, stdout: '' };
       return { status: 0, stdout: JSON.stringify({ version: '24.1.2', node: file, bun: false }) };
     }
     if (args[1] === '--version') return { status: existsSync(args[0]) && readFileSync(args[0], 'utf8') === 'fixture-npm' ? 0 : 1, stdout: '11.0.0\n' };
@@ -37,7 +38,7 @@ function fixture(t) {
   };
   const options = { root, node: join(root, 'missing-node'), platform, arch, libc: 'glibc', run,
     download: async (url, destination) => { calls++; if (url.endsWith('SHASUMS256.txt')) writeFileSync(destination, manifest); else copyFileSync(archive, destination); } };
-  return { root, options, archive, key, cache: join(root, '.pbai4devs/tools/.cache/runtime/node', key), setManifest: value => { manifest = value; }, calls: () => calls };
+  return { root, options, archive, key, cache: join(root, '.pbai4devs/tools/.cache/runtime/node', key), script: name => write(join(root, '.pbai4devs/scripts', name, 'SCRIPT.mjs'), ''), setManifest: value => { manifest = value; }, calls: () => calls };
 }
 
 test('bootstrap Node extrai arquivo real, verifica npm e reutiliza cache sem rede', async t => {
@@ -92,3 +93,156 @@ test('runtime atual saudável não altera PATH nem grava cache', async t => {
   const result = await ensureRuntime({ root: f.root, minimum: Number(process.versions.node.split('.')[0]) });
   assert.equal(result.source, 'current'); assert.equal(process.env.PATH, original); assert.equal(existsSync(f.cache), false);
 });
+
+test('entrada única prepara runtime, diagnostica e encaminha argumentos e status sem shell', async t => {
+  const f = fixture(t), calls = [];
+  f.script('script com espaços');
+  const args = ['script com espaços', '--flag', 'valor com espaços', '$(não executar)', '', '--', 'final'];
+  const options = { ...f.options, run: (file, argv, settings) => {
+    if (argv[0] === '-p' || argv[1] === '--version' || file === tar) return f.options.run(file, argv, settings);
+    calls.push({ file, argv, settings });
+    return { status: calls.length === 1 ? 0 : 69 };
+  } };
+  assert.equal(await main(['--executar', ...args], options), 69);
+  assert.equal(f.calls(), 2);
+  assert.equal(calls.length, 2);
+  assert.equal(calls[0].file, calls[1].file);
+  assert.deepEqual(calls[0].argv, [join(f.root, '.pbai4devs/scripts/diagnosticar-ambiente/SCRIPT.mjs')]);
+  assert.deepEqual(calls[1].argv, [join(f.root, '.pbai4devs/scripts/executar-script/SCRIPT.mjs'), ...args]);
+  assert.equal(calls[0].settings.cwd, f.root);
+  assert.equal(calls[1].settings.cwd, f.root);
+  assert.equal(calls[1].settings.shell, undefined);
+  assert.equal(calls[1].settings.stdio, 'inherit');
+});
+
+test('falha de diagnóstico impede execução e propaga status', async t => {
+  const f = fixture(t), calls = [];
+  f.script('qualquer');
+  const options = { ...f.options, run: (file, argv, settings) => {
+    if (argv[0] === '-p' || argv[1] === '--version' || file === tar) return f.options.run(file, argv, settings);
+    calls.push(argv); return { status: 23 };
+  } };
+  assert.equal(await main(['--executar', 'qualquer'], options), 23);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0][0], join(f.root, '.pbai4devs/scripts/diagnosticar-ambiente/SCRIPT.mjs'));
+});
+
+test('plano não instala nem diagnostica; usa apenas runtime disponível', async t => {
+  const f = fixture(t), calls = [];
+  f.script('qualquer');
+  await assert.rejects(main(['--executar', '--plan', 'qualquer'], f.options), /prepare o runtime/);
+  assert.equal(f.calls(), 0);
+  assert.equal(existsSync(f.cache), false);
+  await ensureRuntime(f.options);
+  const callsBefore = f.calls();
+  const options = { ...f.options, download: async () => { throw new Error('rede indevida'); }, run: (file, argv, settings) => {
+    if (argv[0] === '-p' || argv[1] === '--version' || file === tar) return f.options.run(file, argv, settings);
+    calls.push(argv); return { status: 0 };
+  } };
+  assert.equal(await main(['--executar', '--plan', 'qualquer', 'argumento'], options), 0);
+  assert.equal(f.calls(), callsBefore);
+  assert.deepEqual(calls, [[join(f.root, '.pbai4devs/scripts/executar-script/SCRIPT.mjs'), '--plan', 'qualquer', 'argumento']]);
+});
+
+test('--no-install falha sem runtime e usa cache sem rede; preserva flag do alvo', async t => {
+  const f = fixture(t), calls = [];
+  f.script('alvo');
+  await assert.rejects(main(['--executar', '--no-install', 'alvo'], f.options), /prepare o runtime/);
+  assert.equal(f.calls(), 0);
+  assert.equal(existsSync(f.cache), false);
+  await ensureRuntime(f.options);
+  const options = { ...f.options, download: async () => { throw new Error('rede indevida'); }, run: (file, argv, settings) => {
+    if (argv[0] === '-p' || argv[1] === '--version' || file === tar) return f.options.run(file, argv, settings);
+    calls.push(argv); return { status: 0 };
+  } };
+  assert.equal(await main(['--executar', '--no-install', 'alvo', '--no-install'], options), 0);
+  assert.equal(calls.length, 2);
+  assert.deepEqual(calls[1], [join(f.root, '.pbai4devs/scripts/executar-script/SCRIPT.mjs'), 'alvo', '--no-install']);
+  calls.length = 0;
+  assert.equal(await main(['--executar', '--plan', '--no-install', 'alvo'], options), 0);
+  assert.deepEqual(calls, [[join(f.root, '.pbai4devs/scripts/executar-script/SCRIPT.mjs'), '--plan', 'alvo']]);
+});
+
+test('modo novo encontra Node 24 no PATH com espaços sem baixar runtime', async t => {
+  const f = fixture(t), calls = [], bin = join(f.root, 'bin com espaços');
+  f.script('alvo');
+  mkdirSync(join(bin, 'node_modules/npm/bin'), { recursive: true });
+  const executable = join(bin, process.platform === 'win32' ? 'node.exe' : 'node');
+  writeFileSync(executable, 'fixture-node');
+  if (process.platform !== 'win32') chmodSync(executable, 0o755);
+  writeFileSync(join(bin, 'node_modules/npm/bin/npm-cli.js'), 'fixture-npm');
+  const options = { ...f.options, environment: { PATH: bin }, download: async () => { throw new Error('rede indevida'); }, run: (file, argv, settings) => {
+    if (argv[0] === '-p' || argv[1] === '--version') return f.options.run(file, argv, settings);
+    calls.push({ file, argv }); return { status: 0 };
+  } };
+  const runtime = await ensureRuntime({ ...options, searchPath: true, allowDownload: false });
+  assert.equal(runtime.source, 'path');
+  assert.equal(runtime.node, executable);
+  assert.equal(await main(['--executar', '--no-install', 'alvo', 'argumento com espaços'], options), 0);
+  assert.equal(calls.length, 2);
+  assert.equal(calls[1].file, executable);
+  assert.deepEqual(calls[1].argv.slice(-2), ['alvo', 'argumento com espaços']);
+  assert.equal(existsSync(f.cache), false);
+  assert.equal(f.calls(), 0);
+});
+
+test('entrada única sem alvo falha antes de preparar runtime', async t => {
+  const f = fixture(t);
+  for (const args of [['--executar'], ['--executar', '--plan'], ['--executar', '--no-install'], ['--executar', '--plan', '--no-install']]) await assert.rejects(main(args, f.options), /nome-ou-caminho/);
+  assert.equal(f.calls(), 0);
+  assert.equal(existsSync(f.cache), false);
+});
+
+test('ajuda não procura runtime, acessa rede ou inicia diagnóstico', async t => {
+  const f = fixture(t), unexpected = [];
+  const options = { ...f.options, run: (...args) => { unexpected.push(args); return f.options.run(...args); } };
+  for (const args of [['--executar', '--help'], ['--executar', '-h'], ['--executar', '--no-install', '--plan', '--help']]) assert.equal(await main(args, options), 0);
+  assert.equal(unexpected.length, 0);
+  assert.equal(f.calls(), 0);
+  assert.equal(existsSync(f.cache), false);
+});
+
+test('alvo ou configuração inválida falha antes de runtime, rede e diagnóstico', async t => {
+  const f = fixture(t), scripts = join(f.root, '.pbai4devs/scripts');
+  const invalid = join(scripts, 'invalido'); mkdirSync(invalid, { recursive: true });
+  writeFileSync(join(invalid, 'SCRIPT.mjs'), '');
+  writeFileSync(join(invalid, 'SCRIPT.conf'), 'executor=desconhecido\n');
+  writeFileSync(join(f.root, 'shell.sh'), '');
+  const unexpected = [];
+  const options = { ...f.options, run: (...args) => { unexpected.push(args); return f.options.run(...args); } };
+  for (const target of ['ausente', 'invalido', 'shell.sh', '../fora.mjs']) {
+    await assert.rejects(main(['--executar', target], options), /ausente|SCRIPT.conf|JavaScript|fora/);
+  }
+  assert.equal(unexpected.length, 0);
+  assert.equal(f.calls(), 0);
+  assert.equal(existsSync(f.cache), false);
+});
+
+test('CLI preserva código do seletor quando alvo não existe', t => {
+  const f = fixture(t), target = join(f.root, 'ausente.mjs');
+  const selector = join(project, '.pbai4devs/scripts/executar-script/SCRIPT.mjs');
+  const bootstrap = join(project, '.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs');
+  const direct = spawnSync(process.execPath, [selector, target], { encoding: 'utf8', timeout: 30000 });
+  const viaBootstrap = spawnSync(process.execPath, [bootstrap, '--executar', target], { encoding: 'utf8', timeout: 30000 });
+  assert.equal(direct.status, 2, direct.stderr);
+  assert.equal(viaBootstrap.status, direct.status, viaBootstrap.stderr);
+  assert.match(viaBootstrap.stderr, /ausente/);
+  assert.doesNotMatch(viaBootstrap.stdout, /node=/);
+  assert.equal(existsSync(f.cache), false);
+});
+
+test('diagnóstico real bem-sucedido não garante dependências do alvo', { timeout: 180000 }, t => {
+  const root = mkdtempSync(join(tmpdir(), 'adk-bootstrap-integration-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const cli = spawnSync(process.execPath, [join(project, 'bin/agentdevkit.mjs'), 'init', '--agents', 'codex', '--target', root, '--json'], { encoding: 'utf8', timeout: 120000 });
+  assert.equal(cli.status, 0, `${cli.error?.message || ''}\n${cli.stderr}\n${cli.stdout}`);
+  const target = join(root, 'probe.cjs');
+  writeFileSync(target, `const {spawnSync}=require('node:child_process'); const p=spawnSync('adk-tool-nao-existe-197834',[]); console.log('DEPENDENCIA_AUSENTE='+(p.error?.code==='ENOENT')); process.exit(29);\n`);
+  const environment = { ...process.env, PATH: dirname(process.execPath), Path: dirname(process.execPath) };
+  const bootstrap = join(root, '.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs');
+  const result = spawnSync(process.execPath, [bootstrap, '--executar', '--no-install', 'probe.cjs'], { cwd: root, env: environment, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024 });
+  assert.equal(result.status, 29, `${result.error?.message || ''}\n${result.stderr}\n${result.stdout}`);
+  assert.match(result.stdout, /"tools"\s*:/);
+  assert.match(result.stdout, /runtime=node/);
+  assert.match(result.stdout, /DEPENDENCIA_AUSENTE=true/);
+});

package/.pbai4devs/skills/projeto/executar-script/SKILL.md

@@ -5,20 +5,30 @@ description: Identifica ferramentas instaladas e executa scripts pelo interpreta
 
 # Executar script
 
-No início, confira Node.js 24+ e npm. Com Node 18+, execute o
-[bootstrap JavaScript](../../../scripts/preparar-ferramentas/BOOTSTRAP.md)
-com `--runtime-only` para preparar o núcleo. Sem Node, instale-o primeiro
-pelo mecanismo nativo do SO. Preserve a operação originalmente solicitada.
-Faça o preparo pelo usuário e reutilize o caminho absoluto informado, sem
-depender de PATH global. Execute
-`diagnosticar-ambiente` pelo seletor de [scripts](../../../scripts/README.md).
-Reutilize a verificação enquanto o ambiente não mudar.
+Com Node 18+ e npm, use o bootstrap para preparar Node 24+, diagnosticar e
+executar o script solicitado, nessa ordem:
 
-Prefira scripts existentes a reconstruir automações na conversa. Use
-`--plan <nome-ou-caminho>` para consultar a execução e confira pré-requisitos,
-efeitos e autorização da tarefa. Depois execute com os argumentos originais.
-Após o preparo, automações usam `.mjs`, iguais em todos os sistemas. O seletor usa
-o Node atual, preserva argumentos e códigos de saída e não instala dependências.
+```sh
+node .pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs --executar <script> [argumentos...]
+```
+
+Se o diagnóstico falhar, inspecione a causa; o script não é executado. Seu
+sucesso indica inventário concluído, não dependências necessariamente prontas.
+`--executar --no-install`
+evita apenas o download e instalação do runtime; usa o atual, o primeiro Node
+do PATH ou o cache, se compatível. Não restringe o diagnóstico ou script filho.
+Quando rede ou
+instalações forem proibidas, só execute etapas comprovadamente compatíveis com
+essas restrições ou use isolamento adequado. Sem Node/npm, instale-os pelo
+mecanismo do SO quando autorizado. Preserve a operação e os argumentos pedidos.
+
+Prefira scripts existentes. Use `--executar --plan <script>` para consultar a
+execução sem instalar nem diagnosticar; o plano usa as mesmas opções de runtime.
+Confira pré-requisitos, efeitos e autorização, e execute sem `--plan`.
+O seletor direto continua disponível e não faz preparo nem diagnóstico.
+O bootstrap reúne na saída informações do runtime, diagnóstico e execução;
+identifique cada trecho antes de relatar o resultado do script.
+Consulte a [referência](../../../scripts/executar-script/README.md).
 
 Se indicar `playwright-mcp`, use o conector conforme a
 [referência](../../../scripts/testar-navegador/REFERENCE.md). Não execute esse

package/CHANGELOG.md

@@ -4,6 +4,13 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.28 — 2026-11-14
+
+- Encadeia preparo do runtime, diagnóstico e execução por `--executar`, com
+  plano somente de leitura e opção de não instalar o runtime.
+- Rejeita alvos inválidos antes de preparar o ambiente e reconhece o primeiro
+  Node compatível no PATH; documenta os limites de saída e isolamento.
+
 ## 0.0.27 — 2026-11-14
 
 - Esclarece que desativar locks opcionais não garante a preservação dos bytes

package/package.json

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