@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/scripts/executar-script/tests/TEST.mjs

@@ -0,0 +1,122 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { resolveScript } from '../SCRIPT.mjs';
+import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+
+const script = fileURLToPath(new URL('../SCRIPT.mjs', import.meta.url));
+const run = (...args) => spawnSync(process.execPath, [script, ...args], { encoding: 'utf8' });
+function createSymlink(t, target, path, type) {
+  try { symlinkSync(target, path, type); return true; }
+  catch (error) {
+    if (!['EPERM', 'EACCES'].includes(error.code)) throw error;
+    t.skip('Sistema sem permissao para criar symlinks de teste.');
+    return false;
+  }
+}
+function fixture(t) {
+  mkdirSync(join(projectRoot, '.agent-tests'), { recursive: true });
+  const root = mkdtempSync(join(projectRoot, '.agent-tests/executor-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const write = (path, content) => { const file = join(root, path); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, content); return file; };
+  return { root, write };
+}
+
+test('Node 24 e necessario e nao ha tentativa de runtime alternativo', () => {
+  assert.doesNotThrow(() => requireNode(24, '24.0.0'));
+  assert.throws(() => requireNode(24, '22.22.0'), /Node.js >=24/);
+});
+
+test('plan resolve pasta ou arquivo sem executar; argumentos e cwd sao preservados', t => {
+  const { root, write } = fixture(t); const marker = join(root, 'output.json');
+  const file = write('com espacos/SCRIPT.mjs', `import { writeFileSync } from 'node:fs'; writeFileSync(process.argv[2], JSON.stringify({args:process.argv.slice(3),cwd:process.cwd()}));`);
+  const planned = run('--plan', dirname(file), marker); assert.equal(planned.status, 0, planned.stderr); assert.match(planned.stdout, /runtime=node/); assert.equal(existsSync(marker), false);
+  const value = 'espacos;$(nao execute)'; const result = run(file, marker, value, '--option');
+  assert.equal(result.status, 0, result.stderr); assert.deepEqual(JSON.parse(readFileSync(marker, 'utf8')), { args: [value, '--option'], cwd: projectRoot });
+});
+
+test('nomes encontram SCRIPT.mjs; falha nao executa outra variante', t => {
+  assert.match(run('--plan', 'preparar-ferramentas').stdout, /preparar-ferramentas\/SCRIPT.mjs/);
+  const { root, write } = fixture(t); const file = write('failed/SCRIPT.mjs', 'process.exit(23);');
+  write('failed/SCRIPT.js', `throw new Error('Nao deve executar variante alternativa');`);
+  const result = run(dirname(file)); assert.equal(result.status, 23); assert.doesNotMatch(result.stderr, /alternativa/);
+  assert.equal(resolveScript(file).file, file); assert.equal(existsSync(join(root, 'unused')), false);
+});
+
+test('shell e Python sao recusados mesmo quando executaveis; js e cjs usam Node', t => {
+  const { write } = fixture(t);
+  for (const name of ['SCRIPT.sh', 'SCRIPT.ps1', 'SCRIPT.cmd', 'SCRIPT.bat', 'SCRIPT.py']) assert.equal(run(write(name, 'exit 0')).status, 2);
+  for (const name of ['file.js', 'file.cjs']) {
+    const result = run(write(name, "console.log('node=passed');")); assert.equal(result.status, 0, result.stderr); assert.match(result.stdout, /node=passed/);
+  }
+});
+
+test('caminhos fora da raiz, symlinks de arquivo, pasta ou conf nao escapam da contencao', async t => {
+  const { root, write } = fixture(t); const workspace = join(root, 'workspace'); mkdirSync(workspace);
+  const external = write('outside.mjs', 'process.exit(0);');
+  assert.throws(() => resolveScript(external, { root: workspace }), /fora do repositorio/);
+  const internal = write('workspace/inside/SCRIPT.mjs', 'process.exit(0);');
+  await t.test('arquivo simbolico', subtest => {
+    if (!createSymlink(subtest, internal, join(workspace, 'alias.mjs'))) return;
+    assert.throws(() => resolveScript(join(workspace, 'alias.mjs'), { root: workspace }), /simbolico/);
+  });
+  await t.test('diretorio simbolico', subtest => {
+    if (!createSymlink(subtest, dirname(internal), join(workspace, 'alias-dir'), 'dir')) return;
+    assert.throws(() => resolveScript(join(workspace, 'alias-dir/SCRIPT.mjs'), { root: workspace }), /simbolico/);
+  });
+  await t.test('configuracao simbolica', subtest => {
+    const config = write('real.conf', 'executor=playwright-mcp');
+    if (!createSymlink(subtest, config, join(dirname(internal), 'SCRIPT.conf'))) return;
+    assert.throws(() => resolveScript(internal, { root: workspace }), /simbolico/);
+  });
+  await t.test('configuracao simbolica sem alvo', subtest => {
+    const script = write('workspace/dangling/SCRIPT.mjs', 'process.exit(0);');
+    if (!createSymlink(subtest, join(workspace, 'missing.conf'), join(dirname(script), 'SCRIPT.conf'))) return;
+    assert.throws(() => resolveScript(script, { root: workspace }), /simbolico/);
+  });
+});
+
+test('Playwright mantem plano e codigo 69 sem executar o arquivo de conector', t => {
+  const { root, write } = fixture(t); const marker = join(root, 'should-not-exist');
+  const file = write('browser/SCRIPT.js', `require('node:fs').writeFileSync(${JSON.stringify(marker)}, 'bad');`);
+  write('browser/SCRIPT.conf', 'executor=playwright-mcp\n');
+  const plan = run('--plan', dirname(file)); assert.equal(plan.status, 0); assert.match(plan.stdout, /executor=playwright-mcp/);
+  const result = run(dirname(file)); assert.equal(result.status, 69); assert.match(result.stderr, /conector Playwright/); assert.equal(existsSync(marker), false);
+});
+
+test('configuracao invalida nunca recai em Node nem executa outro script', t => {
+  const { root, write } = fixture(t);
+  const marker = join(root, 'must-not-run');
+  const file = write('configured/SCRIPT.mjs', `import { writeFileSync } from 'node:fs'; writeFileSync(${JSON.stringify(marker)}, 'bad');`);
+  for (const config of ['', '# comentario\n', 'executor=python\n', 'other=node\n', 'executor=node\nexecutor=node\n', 'executor=node\nexecutor=playwright-mcp\n']) {
+    write('configured/SCRIPT.conf', config);
+    const result = run(file);
+    assert.equal(result.status, 2, result.stderr);
+    assert.match(result.stderr, /SCRIPT.conf exige/);
+    assert.equal(existsSync(marker), false);
+  }
+  write('configured/SCRIPT.conf', '# Node explicito\n executor = node \n');
+  assert.equal(resolveScript(file).executor, 'node');
+});
+
+test('configuracao e alvo do conector precisam ser arquivos regulares', t => {
+  const { root, write } = fixture(t);
+  const script = write('bad-config/SCRIPT.mjs', 'process.exit(0);');
+  mkdirSync(join(dirname(script), 'SCRIPT.conf'));
+  assert.throws(() => resolveScript(script), /SCRIPT.conf deve ser um arquivo/);
+  write('bad-connector/SCRIPT.conf', 'executor=playwright-mcp\n');
+  mkdirSync(join(root, 'bad-connector/SCRIPT.js'));
+  assert.throws(() => resolveScript(join(root, 'bad-connector')), /SCRIPT.js do conector deve ser um arquivo/);
+  const alternate = write('connector/other.mjs', 'process.exit(0);');
+  write('connector/SCRIPT.conf', 'executor=playwright-mcp\n');
+  write('connector/SCRIPT.js', 'page.title();');
+  assert.throws(() => resolveScript(alternate), /exige o arquivo SCRIPT.js configurado/);
+});
+
+test('ausencia ou caminho invalido falha sem procurar interpretes do sistema', () => {
+  assert.equal(run().status, 2); assert.equal(run('missing-agent-script').status, 2);
+  assert.equal(run('--help').status, 0);
+});

package/.pbai4devs/scripts/gerenciar-skills-externas/README.md

@@ -0,0 +1,31 @@
+---
+description: Instala e verifica skills externas do catálogo revisado.
+---
+
+# Gerenciar skills externas
+
+Use Node.js 24+ e prepare o CLI com
+`node .pbai4devs/tools/skills/SCRIPT.mjs install`. Os comandos aceitam um ID do
+[catálogo](../../external-skills/CATALOG.json):
+
+```console
+node .pbai4devs/scripts/gerenciar-skills-externas/SCRIPT.mjs list
+node .pbai4devs/scripts/gerenciar-skills-externas/SCRIPT.mjs discover cloudflare-web-perf
+node .pbai4devs/scripts/gerenciar-skills-externas/SCRIPT.mjs install cloudflare-web-perf
+node .pbai4devs/scripts/gerenciar-skills-externas/SCRIPT.mjs check cloudflare-web-perf
+node .pbai4devs/scripts/gerenciar-skills-externas/SCRIPT.mjs read cloudflare-web-perf
+```
+
+`list`, `check` e `read` não acessam a rede. `discover` lista a origem fixada
+usando o CLI oficial. `install` reutiliza a cópia verificada; `update <id>`
+aplica o pin revisado do catálogo ou restaura conteúdo local alterado. Revise
+origem, licença e instruções antes de mudar uma entrada para `reviewed`.
+
+Downloads usam `skills add` com `--agent universal --copy --yes`, em pasta
+isolada. O gerenciador confere origem, SHA, caminho e conteúdo; preserva a
+instalação anterior quando o preparo falha. Ele não chama `skills update`,
+não executa scripts da skill e não altera o catálogo nem os espelhos.
+A subpasta `.agents/skills` dentro do download é o formato do CLI universal;
+ela permanece no cache de `.pbai4devs`, sem ocupar o espelho `.agents` do projeto.
+
+Teste offline: `node --test .pbai4devs/scripts/gerenciar-skills-externas/tests/TEST.mjs`.

package/.pbai4devs/scripts/gerenciar-skills-externas/SCRIPT.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep, posix } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { projectRoot, requireNode, isMain } from '../lib/runtime.mjs';
+import { ToolManager, binaryInvocation, toolEnvironment } from '../preparar-ferramentas/SCRIPT.mjs';
+
+const fail = message => { throw new Error(message); };
+const json = file => JSON.parse(readFileSync(file, 'utf8'));
+const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const repository = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*\/[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+const stat = file => { try { return lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+
+export function safePath(root, path) {
+  const full = resolve(root, path); const part = relative(root, full);
+  if (isAbsolute(part) || part === '..' || part.startsWith(`..${sep}`)) fail('Caminho fora da pasta permitida.');
+  let current = root;
+  for (const name of part.split(sep).filter(Boolean)) {
+    if (stat(current)?.isDirectory() && readdirSync(current).some(existing => existing !== name && existing.toLowerCase() === name.toLowerCase())) fail(`Caixa conflitante: ${full}`);
+    current = join(current, name);
+    if (stat(current)?.isSymbolicLink()) fail(`Link simbolico nao permitido: ${full}`);
+  }
+  return full;
+}
+
+export function validateCatalog(value) {
+  if (value?.schemaVersion !== 1 || !Array.isArray(value.allowlist) || !Array.isArray(value.skills)) fail('Catalogo externo invalido.');
+  const allowed = new Set(); const ids = new Set();
+  for (const source of value.allowlist) {
+    if (typeof source !== 'string' || !repository.test(source) || allowed.has(source.toLowerCase())) fail('Origem duplicada ou invalida na allowlist.');
+    allowed.add(source.toLowerCase());
+  }
+  for (const entry of value.skills) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) fail('Entrada de skill invalida.');
+    if (!slug.test(entry.id || '') || ids.has(entry.id)) fail('Identificador de skill invalido ou duplicado.');
+    ids.add(entry.id);
+    if (!repository.test(entry.repository || '') || !allowed.has(entry.repository.toLowerCase())) fail(`Origem fora da allowlist: ${entry.id}`);
+    if (!/^[a-f0-9]{40}$/.test(entry.commit || '')) fail(`Use SHA completo e imutavel: ${entry.id}`);
+    if (typeof entry.path !== 'string' || !entry.path.endsWith('/SKILL.md') || entry.path.includes('\\') || /[\x00-\x1f]/.test(entry.path) || entry.path.split('/').some(part => !part || part === '.' || part === '..' || part.includes(':'))) fail(`Caminho de skill invalido: ${entry.id}`);
+    if (!slug.test(entry.name || '') || typeof entry.license !== 'string' || !entry.license.trim() || typeof entry.use !== 'string' || !entry.use.trim() || !['candidate', 'reviewed'].includes(entry.status)) fail(`Metadados incompletos: ${entry.id}`);
+    if (entry.notes !== undefined && typeof entry.notes !== 'string') fail(`Notas invalidas: ${entry.id}`);
+    if (entry.licenseSource !== undefined) {
+      const license = new URL(entry.licenseSource);
+      if (license.origin !== 'https://github.com' || !license.pathname.startsWith(`/${entry.repository}/blob/${entry.commit}/`)) fail(`Referencia de licenca deve usar a mesma origem e pin: ${entry.id}`);
+    }
+  }
+  return value;
+}
+
+export function loadCatalog(root = projectRoot) {
+  return validateCatalog(json(safePath(realpathSync(root), '.pbai4devs/external-skills/CATALOG.json')));
+}
+
+export function sourceUrl(entry) {
+  return `https://github.com/${entry.repository}/tree/${entry.commit}/${posix.dirname(entry.path).split('/').map(encodeURIComponent).join('/')}`;
+}
+
+export function skillsArguments(entry, list = false) {
+  return ['add', sourceUrl(entry), '--skill', entry.name, ...(list ? ['--list'] : ['--agent', 'universal', '--copy', '--yes'])];
+}
+
+export function runSkills(root, cwd, args) {
+  const manager = new ToolManager({ root }); const entry = manager.entry('skills'); const installed = manager.check('skills'); const runtime = manager.runtime('skills');
+  const [file, argv] = binaryInvocation(installed.prefix, entry.download.package, args, entry.binary || entry.name, runtime.file);
+  const environment = toolEnvironment(entry, manager.local('skills'), runtime);
+  environment.DISABLE_TELEMETRY = '1'; environment.CI = '1'; environment.XDG_STATE_HOME = join(cwd, '.state');
+  const result = spawnSync(file, argv, { cwd, env: environment, encoding: 'utf8', timeout: 180000, windowsHide: true });
+  if (result.error || result.status !== 0) fail(`skills: ${result.error?.message || result.stderr?.trim().slice(0, 600) || result.stdout?.trim().slice(0, 600) || result.status}`);
+  return result.stdout || '';
+}
+
+function descriptor(entry) {
+  return { id: entry.id, name: entry.name, repository: entry.repository, commit: entry.commit, path: entry.path, license: entry.license };
+}
+
+function payloadHash(folder) {
+  const hash = createHash('sha256');
+  function visit(path) {
+    for (const name of readdirSync(path).sort()) {
+      const file = safePath(folder, relative(folder, join(path, name))); const info = lstatSync(file);
+      if (info.isDirectory()) visit(file);
+      else if (info.isFile()) {
+        const label = relative(folder, file).split(sep).join('/'); const content = readFileSync(file);
+        hash.update(`${Buffer.byteLength(label)}:${label}:${content.length}:`); hash.update(content);
+      } else fail(`Arquivo de skill nao regular: ${file}`);
+    }
+  }
+  visit(folder);
+  return hash.digest('hex');
+}
+
+export class ExternalSkills {
+  constructor({ root = projectRoot, catalog, run = runSkills } = {}) {
+    requireNode(); this.root = realpathSync(root); this.catalog = validateCatalog(catalog ?? loadCatalog(this.root)); this.run = run;
+    this.home = safePath(this.root, '.pbai4devs/external-skills');
+  }
+  entry(id, reviewed = false) {
+    const entry = this.catalog.skills.find(item => item.id === id);
+    if (!entry) fail(`Skill externa desconhecida: ${id}`);
+    if (reviewed && entry.status !== 'reviewed') fail(`Revise origem, pin, licenca e instrucoes antes de instalar: ${id}`);
+    return entry;
+  }
+  local(id) { this.entry(id); return safePath(this.home, `.local/${id}`); }
+  validatePayload(folder, entry) {
+    safePath(this.home, relative(this.home, folder));
+    // O CLI skills usa .agents no staging universal, independentemente do hub.
+    const skills = safePath(folder, '.agents/skills');
+    const names = readdirSync(skills).sort();
+    if (names.length !== 1 || names[0] !== entry.name) fail(`Esperada somente a skill ${entry.name}.`);
+    const payload = safePath(folder, `.agents/skills/${entry.name}`); const file = safePath(payload, 'SKILL.md');
+    const text = readFileSync(file, 'utf8'); const lines = text.replaceAll('\r', '').split('\n'); const closing = lines.indexOf('---', 1);
+    if (lines[0] !== '---' || closing < 1 || !lines.slice(1, closing).some(line => new RegExp(`^name:\\s*['\"]?${entry.name}['\"]?\\s*$`).test(line))) fail('Nome ou frontmatter da skill instalado divergente.');
+    const lock = json(safePath(folder, 'skills-lock.json')); const source = lock.skills?.[entry.name];
+    if (lock.version !== 2 || Object.keys(lock.skills || {}).length !== 1 || source?.sourceType !== 'github' || source.source?.toLowerCase() !== entry.repository.toLowerCase() || source.ref !== entry.commit || source.skillPath !== entry.path || !/^[a-f0-9]{64}$/.test(source.computedHash || '')) fail('Proveniencia do lock diverge do catalogo revisado.');
+    for (const name of readdirSync(folder)) if (!['.agents', '.state', 'skills-lock.json', 'CURRENT.json'].includes(name)) fail(`Saida inesperada do CLI: ${name}`);
+    if (readdirSync(join(folder, '.agents')).some(name => name !== 'skills')) fail('Saida inesperada fora da origem unica da skill.');
+    return { file, hash: payloadHash(payload) };
+  }
+  check(id) {
+    const entry = this.entry(id, true); const folder = this.local(id);
+    const receiptPath = safePath(folder, 'CURRENT.json');
+    if (!existsSync(receiptPath)) fail(`Skill ausente: ${id}; use install ${id}.`);
+    const receipt = json(receiptPath);
+    if (JSON.stringify(receipt.source) !== JSON.stringify(descriptor(entry))) fail(`Pin ou origem mudou; revise o catalogo e use update ${id}.`);
+    const payload = this.validatePayload(folder, entry);
+    if (payload.hash !== receipt.payloadHash) fail(`Conteudo local alterado: ${id}; use update ${id} para restaurar o pin revisado.`);
+    return { id, commit: entry.commit, file: payload.file, license: entry.license };
+  }
+  read(id) { const info = this.check(id); return { ...info, content: readFileSync(info.file, 'utf8') }; }
+  async lock(id, action) {
+    this.entry(id, true); const local = safePath(this.home, '.local'); mkdirSync(local, { recursive: true });
+    const lock = safePath(local, `.${id}.lock`);
+    try { mkdirSync(lock); } catch (error) { if (error.code === 'EEXIST') fail(`Operacao em andamento: ${id}`); throw error; }
+    try { return await action(local); } finally { rmSync(lock, { recursive: true, force: true }); }
+  }
+  async install(id) {
+    this.entry(id, true);
+    if (stat(this.local(id))) return { ...this.check(id), changed: false };
+    return this.replace(id);
+  }
+  async update(id) {
+    this.entry(id, true);
+    try { return { ...this.check(id), changed: false }; } catch { return this.replace(id); }
+  }
+  async replace(id) {
+    const entry = this.entry(id, true);
+    return this.lock(id, async local => {
+      const stage = mkdtempSync(join(local, `.stage-${id}-`)); const target = this.local(id); let previous;
+      try {
+        await this.run(this.root, stage, skillsArguments(entry));
+        const payload = this.validatePayload(stage, entry);
+        writeFileSync(join(stage, 'CURRENT.json'), JSON.stringify({ source: descriptor(entry), payloadHash: payload.hash, installedAt: new Date().toISOString() }, null, 2) + '\n');
+        if (stat(target)) { previous = join(local, `.previous-${id}-${randomUUID()}`); renameSync(target, previous); }
+        try { renameSync(stage, target); }
+        catch (error) { if (previous) renameSync(previous, target); throw error; }
+        if (previous) rmSync(previous, { recursive: true, force: true });
+        return { ...this.check(id), changed: true };
+      } finally { rmSync(stage, { recursive: true, force: true }); }
+    });
+  }
+  async discover(id) {
+    const entry = this.entry(id); const local = safePath(this.home, '.local'); mkdirSync(local, { recursive: true });
+    const stage = mkdtempSync(join(local, `.discover-${id}-`));
+    try { return await this.run(this.root, stage, skillsArguments(entry, true)); }
+    finally { rmSync(stage, { recursive: true, force: true }); }
+  }
+}
+
+export async function main(input = process.argv.slice(2), manager) {
+  requireNode(); const [mode = 'help', id, ...extra] = input;
+  if (['help', '--help', '-h'].includes(mode)) { console.log('Uso: list | discover <id> | install <id> | check <id> | update <id> | read <id>. Atualizacoes exigem pin revisado no CATALOG.json.'); return 0; }
+  manager ??= new ExternalSkills();
+  if (mode === 'list' && !id && !extra.length) { for (const entry of manager.catalog.skills) console.log(JSON.stringify(entry)); return 0; }
+  if (!['discover', 'install', 'check', 'update', 'read'].includes(mode) || !id || extra.length) fail('Use uma acao e um unico id do catalogo; consulte --help.');
+  const result = await manager[mode](id); console.log(typeof result === 'string' ? result.trim() : JSON.stringify(result)); return 0;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = await main(); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/.pbai4devs/scripts/gerenciar-skills-externas/tests/TEST.mjs

@@ -0,0 +1,134 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { ExternalSkills, loadCatalog, main, runSkills, safePath, skillsArguments, sourceUrl, validateCatalog } from '../SCRIPT.mjs';
+import { projectRoot } from '../../lib/runtime.mjs';
+
+function write(file, text) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, text); }
+const sample = () => ({ id: 'vendor-demo', repository: 'vendor/skills', commit: 'a'.repeat(40), path: 'skills/demo/SKILL.md', name: 'demo', license: 'MIT', use: 'Teste offline.', status: 'reviewed' });
+const contents = entry => `---\nname: ${entry.name}\ndescription: Fixture.\n---\n\n# Demo\n\nConteudo ${entry.commit}.\n`;
+function fixture(t) {
+  mkdirSync(join(projectRoot, '.agent-tests'), { recursive: true });
+  const root = mkdtempSync(join(projectRoot, '.agent-tests/external-skills-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const entry = sample(); const catalog = { schemaVersion: 1, allowlist: ['vendor/skills'], skills: [entry] };
+  write(join(root, '.pbai4devs/external-skills/CATALOG.json'), JSON.stringify(catalog));
+  const state = { calls: [], fail: false, corrupt: false, extra: false };
+  const manager = new ExternalSkills({ root, catalog, run: async (_root, cwd, args) => {
+    state.calls.push({ cwd, args });
+    if (state.fail) throw new Error('download interrompido');
+    if (args.includes('--list')) return 'demo: Fixture.';
+    const base = join(cwd, '.agents/skills', entry.name);
+    write(join(base, 'SKILL.md'), contents(entry));
+    write(join(base, 'references/REFERENCE.md'), '# Referencia preservada\n');
+    write(join(base, 'LICENSE.txt'), 'MIT fixture\n');
+    const lock = { version: 2, skills: { [entry.name]: { source: state.corrupt ? 'other/repo' : entry.repository, ref: entry.commit, skillPath: entry.path, sourceType: 'github', computedHash: 'a'.repeat(64) } } };
+    write(join(cwd, 'skills-lock.json'), JSON.stringify(lock));
+    if (state.extra) write(join(cwd, '.codex/skills/demo/SKILL.md'), contents(entry));
+  } });
+  return { root, catalog, entry, state, manager, local: join(root, '.pbai4devs/external-skills/.local') };
+}
+
+test('catalogo aceita somente origens permitidas, pins completos e metadados de revisao', t => {
+  const { root, catalog } = fixture(t);
+  assert.equal(loadCatalog(root).skills[0].id, 'vendor-demo');
+  for (const change of [{ commit: 'main' }, { commit: 'a'.repeat(39) }, { repository: 'evil/skills' }, { path: '../SKILL.md' }, { path: 'skills\\demo\\SKILL.md' }, { name: '../demo' }, { id: '../demo' }, { status: 'approved' }, { license: '' }, { use: '' }]) {
+    assert.throws(() => validateCatalog({ ...catalog, skills: [{ ...sample(), ...change }] }));
+  }
+  assert.throws(() => validateCatalog({ ...catalog, skills: [sample(), sample()] }), /duplicado/);
+  assert.throws(() => validateCatalog({ ...catalog, allowlist: ['vendor/skills', 'VENDOR/skills'] }), /duplicada/);
+  assert.throws(() => validateCatalog({ ...catalog, skills: [{ ...sample(), notes: {} }] }), /Notas invalidas/);
+  assert.throws(() => validateCatalog({ ...catalog, skills: [{ ...sample(), licenseSource: 'https://github.com/vendor/skills/blob/main/LICENSE' }] }), /mesma origem e pin/);
+});
+
+test('ajuda e listagem sao locais e nao criam estado', async t => {
+  const { manager, state, local } = fixture(t);
+  await main([], manager); await main(['list'], manager);
+  assert.equal(state.calls.length, 0); assert.equal(existsSync(local), false);
+  await assert.rejects(main(['install', 'unknown'], manager), /desconhecida/);
+  await assert.rejects(main(['install', 'vendor-demo', 'extra'], manager), /unico id/);
+});
+
+test('candidatos nao sao instalados; descoberta usa somente origem fixada sem importar', async t => {
+  const { manager, entry, state, local } = fixture(t); entry.status = 'candidate';
+  await assert.rejects(manager.install(entry.id), /Revise origem/); assert.equal(existsSync(local), false);
+  const result = await manager.discover(entry.id); assert.equal(result, 'demo: Fixture.');
+  assert.deepEqual(state.calls[0].args, ['add', sourceUrl(entry), '--skill', 'demo', '--list']);
+  assert.deepEqual(readdirSync(local), []);
+  assert.throws(() => manager.read(entry.id), /Revise origem/);
+});
+
+test('instala por CLI com copy universal e preserva referencias/licenca em origem isolada', async t => {
+  const { manager, entry, state, root } = fixture(t);
+  const installed = await manager.install(entry.id); assert.equal(installed.changed, true);
+  assert.deepEqual(state.calls[0].args, skillsArguments(entry));
+  assert.ok(state.calls[0].args.includes('--copy')); assert.ok(state.calls[0].args.includes('universal')); assert.ok(!state.calls[0].args.includes('--global'));
+  assert.equal(readFileSync(installed.file, 'utf8'), contents(entry));
+  assert.match(readFileSync(join(dirname(installed.file), 'references/REFERENCE.md'), 'utf8'), /preservada/);
+  assert.match(readFileSync(join(dirname(installed.file), 'LICENSE.txt'), 'utf8'), /MIT/);
+  for (const path of ['.pbai4devs/skills', '.agents/skills', '.codex', '.claude', '.github']) assert.equal(existsSync(join(root, path)), false);
+  assert.equal((await manager.install(entry.id)).changed, false); assert.equal(state.calls.length, 1);
+});
+
+test('check e read sao offline; alteracao local exige restauracao do pin revisado', async t => {
+  const { manager, entry, state } = fixture(t); await manager.install(entry.id);
+  const info = manager.check(entry.id); assert.equal(manager.read(entry.id).content, contents(entry)); assert.equal(state.calls.length, 1);
+  write(info.file, contents(entry) + '\nAlterado.\n'); assert.throws(() => manager.check(entry.id), /Conteudo local alterado/);
+  assert.throws(() => manager.read(entry.id), /Conteudo local alterado/);
+  const result = await manager.update(entry.id); assert.equal(result.changed, true); assert.equal(state.calls.length, 2);
+  assert.equal(manager.read(entry.id).content, contents(entry));
+});
+
+test('update aplica somente mudanca explicita para outro pin reviewed do catalogo', async t => {
+  const { manager, entry, state, root } = fixture(t); await manager.install(entry.id);
+  const catalogFile = join(root, '.pbai4devs/external-skills/CATALOG.json'); const catalogBefore = readFileSync(catalogFile, 'utf8');
+  assert.equal((await manager.update(entry.id)).changed, false); assert.equal(state.calls.length, 1);
+  entry.commit = 'b'.repeat(40); assert.throws(() => manager.check(entry.id), /Pin ou origem mudou/);
+  await assert.rejects(manager.install(entry.id), /Pin ou origem mudou/);
+  entry.status = 'candidate'; await assert.rejects(manager.update(entry.id), /Revise origem/);
+  entry.status = 'reviewed'; await manager.update(entry.id);
+  assert.equal(manager.check(entry.id).commit, entry.commit); assert.ok(state.calls[1].args[1].includes(entry.commit));
+  assert.equal(readFileSync(catalogFile, 'utf8'), catalogBefore);
+});
+
+test('falhas de download, proveniencia ou destinos extras preservam a copia anterior', async t => {
+  const { manager, entry, state, local } = fixture(t); const first = await manager.install(entry.id);
+  const original = readFileSync(first.file, 'utf8'); const receipt = readFileSync(join(manager.local(entry.id), 'CURRENT.json'), 'utf8'); entry.commit = 'b'.repeat(40);
+  for (const mode of ['fail', 'corrupt', 'extra']) {
+    state[mode] = true; await assert.rejects(manager.update(entry.id), /interrompido|Proveniencia|inesperada/); state[mode] = false;
+    assert.equal(readFileSync(first.file, 'utf8'), original); assert.equal(readFileSync(join(manager.local(entry.id), 'CURRENT.json'), 'utf8'), receipt);
+    assert.deepEqual(readdirSync(local), [entry.id]);
+  }
+});
+
+test('locks impedem duas instalacoes simultaneas sem remover lock alheio', async t => {
+  const { manager, entry, state, local } = fixture(t); const originalRun = manager.run; let entered; let proceed;
+  const started = new Promise(resolve => { entered = resolve; }); const ready = new Promise(resolve => { proceed = resolve; });
+  manager.run = async (...args) => { entered(); await ready; return originalRun(...args); };
+  const first = manager.install(entry.id); await started;
+  await assert.rejects(manager.install(entry.id), /Operacao em andamento/);
+  assert.ok(existsSync(join(local, `.${entry.id}.lock`))); proceed(); await first;
+  assert.equal(state.calls.length, 1); assert.deepEqual(readdirSync(local), [entry.id]);
+});
+
+test('estado simbolico nao redireciona escrita para outra pasta', async t => {
+  const { manager, state, local, root } = fixture(t); const outside = join(root, 'outside'); mkdirSync(outside);
+  try { symlinkSync(outside, local, 'dir'); } catch (error) { if (['EPERM', 'EACCES'].includes(error.code)) { t.skip('Sistema sem permissao para symlinks.'); return; } throw error; }
+  assert.throws(() => safePath(manager.home, '.local'), /simbolico/);
+  await assert.rejects(manager.install('vendor-demo'), /simbolico/); assert.equal(state.calls.length, 0); assert.deepEqual(readdirSync(outside), []);
+});
+
+test('CLI skills real copia fixture local sem escrita nas origens canonicas ou globais', async t => {
+  if (!existsSync(join(projectRoot, '.pbai4devs/tools/skills/.local/CURRENT.json'))) { t.skip('CLI skills ainda nao preparado.'); return; }
+  const { root } = fixture(t); const name = `external-proof-${process.pid}`; const source = join(root, 'source'); const target = join(root, 'target'); mkdirSync(target);
+  const entry = { ...sample(), name }; write(join(source, 'SKILL.md'), contents(entry)); write(join(source, 'LICENSE.txt'), 'MIT fixture\n');
+  const canonical = join(projectRoot, '.pbai4devs/skills', name); const global = join(homedir(), '.agents/skills', name);
+  assert.equal(existsSync(canonical), false); assert.equal(existsSync(global), false);
+  runSkills(projectRoot, target, ['add', source, '--skill', name, '--agent', 'universal', '--copy', '--yes']);
+  const file = join(target, '.agents/skills', name, 'SKILL.md'); assert.equal(readFileSync(file, 'utf8'), contents(entry));
+  assert.equal(readFileSync(join(dirname(file), 'LICENSE.txt'), 'utf8'), 'MIT fixture\n');
+  assert.deepEqual(readdirSync(join(target, '.agents/skills')), [name]); assert.equal(existsSync(join(target, '.codex')), false);
+  assert.equal(existsSync(canonical), false); assert.equal(existsSync(global), false);
+});