@pathbit/agentdevkit 0.0.7 → 0.0.9

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

@@ -0,0 +1,35 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+// Inspect native paths without opening a symlink target. Callers restrict this
+// exception to user-owned adapter paths; canonical kit files stay strict.
+export function nativePathBoundary(root, path, ownedPaths = [], { preserveRootAliases = false } = {}) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /[|\\\x00-\x1f\x7f:]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) {
+    throw Object.assign(new Error(`Caminho invalido: ${path}`), { code: 'E_PATH' });
+  }
+  const parts = path.split('/');
+  let current = root;
+  for (const [index, part] of parts.entries()) {
+    try {
+      const aliases = lstatSync(current).isDirectory() ? readdirSync(current).filter(name => name.toLowerCase() === part.toLowerCase() && name !== part).sort() : [];
+      if (aliases.length) {
+        const rootEntry = parts.length === 1 && ['README.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(path);
+        const owned = [...ownedPaths].some(value => value.toLowerCase() === path.toLowerCase() || value.toLowerCase().startsWith(`${path.toLowerCase()}/`));
+        if (preserveRootAliases && rootEntry && !owned) return { path: aliases[0], reason: 'case-variant' };
+        throw Object.assign(new Error(`Caminhos diferem somente por maiusculas/minusculas: ${path}`), { code: 'E_PATH' });
+      }
+    } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; }
+    current = join(current, part);
+    let info;
+    try { info = lstatSync(current); }
+    catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; }
+    const reason = info.isSymbolicLink() ? 'symbolic-link' : index < parts.length - 1 && !info.isDirectory() ? 'non-directory' : null;
+    if (!reason) continue;
+    const boundary = parts.slice(0, index + 1).join('/');
+    if ([...ownedPaths].some(value => value === boundary || value.startsWith(`${boundary}/`))) {
+      throw Object.assign(new Error(`${reason === 'symbolic-link' ? 'Link simbolico' : 'Ancestral nao e diretorio'} em caminho gerenciado: ${boundary}`), { code: reason === 'symbolic-link' ? 'E_SYMLINK' : 'E_PATH' });
+    }
+    return { path: boundary, reason };
+  }
+  return null;
+}

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

@@ -101,6 +101,14 @@ function sourcePath(root, name) {
   return file;
 }
 
+function storagePath(root, name, kind) {
+  const file = sourcePath(root, name);
+  let item;
+  try { item = lstatSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (item && !(kind === 'directory' ? item.isDirectory() : item.isFile())) fail(`Caminho local exige ${kind}: ${name}`);
+  return file;
+}
+
 export function loadCatalog(root = projectRoot) {
   root = realpathSync(root);
   const home = sourcePath(root, '.pbai4devs/tools'); const catalog = Object.create(null);
@@ -272,15 +280,21 @@ export class ToolManager {
     return { mode: 'setup', selection: selected, platform: this.target, node: process.version, nodePath: process.execPath, npm, results: entries, summary, status: summary.failed ? 'failed' : summary.passed ? 'passed' : 'not-applicable', exitCode: summary.failed ? 1 : 0 };
   }
   local(name) { this.entry(name); return join(this.home, name, '.local'); }
+  storage(name) {
+    const local = this.local(name), tool = join(this.home, name);
+    for (const path of [this.home, tool, local, join(local, 'versions'), join(tool, 'versions'), join(this.home, '.cache'), join(this.home, '.cache/npm'), join(this.home, 'npm-cache')]) storagePath(this.root, path, 'directory');
+    for (const path of [join(local, 'CURRENT.json'), join(tool, 'CURRENT.json')]) storagePath(this.root, path, 'file');
+    return { local, tool };
+  }
   current(name) {
-    this.entry(name);
-    const local = this.local(name); const legacy = join(this.home, name);
+    const { local, tool: legacy } = this.storage(name);
     const base = existsSync(join(local, 'CURRENT.json')) ? local : legacy;
     const file = join(base, 'CURRENT.json');
     if (!existsSync(file)) fail(`Ferramenta ausente: ${name}; execute install ${name}.`);
     const info = json(file);
     if (info.name !== name || info.platform !== this.target || !versionPattern.test(info.version || '')) fail(`Instalacao incompativel: ${name}`);
-    return { ...info, layout: base === local ? 'local' : 'legacy', prefix: join(base, 'versions', `${info.version}-${this.target}`) };
+    const prefix = storagePath(this.root, join(base, 'versions', `${info.version}-${this.target}`), 'directory');
+    return { ...info, layout: base === local ? 'local' : 'legacy', prefix };
   }
   check(name) {
     const entry = this.entry(name); const runtime = this.runtime(name); const info = this.current(name);
@@ -306,7 +320,7 @@ export class ToolManager {
     for (const legacy of [name, `${name}.cmd`, `${name}.ps1`, `${name}.sh`]) rmSync(join(bin, legacy), { force: true });
   }
   migrate(name) {
-    const local = this.local(name); const tool = join(this.home, name);
+    const { local, tool } = this.storage(name);
     const legacyState = join(tool, 'CURRENT.json'); const legacyVersions = join(tool, 'versions');
     if (existsSync(legacyState)) {
       if (existsSync(join(local, 'CURRENT.json')) || (existsSync(join(local, 'versions')) && readdirSync(join(local, 'versions')).length)) fail(`Layouts local e antigo coexistem: ${name}; revise antes de migrar.`);
@@ -318,15 +332,15 @@ export class ToolManager {
     }
     const oldCache = join(this.home, 'npm-cache');
     if (existsSync(oldCache)) {
-      const cache = join(this.home, '.cache'); mkdirSync(cache, { recursive: true });
-      try { renameSync(oldCache, join(cache, existsSync(join(cache, 'npm')) ? `npm-legacy-${process.pid}-${Date.now()}` : 'npm')); }
+      const cache = storagePath(this.root, join(this.home, '.cache'), 'directory'); mkdirSync(cache, { recursive: true });
+      const destination = storagePath(this.root, join(cache, existsSync(join(cache, 'npm')) ? `npm-legacy-${randomUUID()}` : 'npm'), 'directory');
+      try { renameSync(oldCache, destination); }
       catch (error) { if (error.code !== 'ENOENT' || existsSync(oldCache)) throw error; }
     }
   }
   async withLock(name, action) {
-    const local = this.local(name);
-    for (const directory of [this.home, join(this.home, name), local]) if (existsSync(directory) && lstatSync(directory).isSymbolicLink()) fail(`Diretorio local nao pode ser um link: ${directory}`);
-    mkdirSync(local, { recursive: true }); const lock = join(local, '.update-lock');
+    const { local } = this.storage(name);
+    mkdirSync(local, { recursive: true }); const lock = storagePath(this.root, join(local, '.update-lock'), 'directory');
     try { mkdirSync(lock); } catch (error) {
       if (error.code === 'EEXIST') {
         const status = this.lockStatus(name);
@@ -334,8 +348,8 @@ export class ToolManager {
       }
       throw error;
     }
-    try { writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, hostname: hostname(), startedAt: new Date().toISOString() })); return await action(); }
-    finally { rmSync(lock, { recursive: true, force: true }); }
+    try { writeFileSync(storagePath(this.root, join(lock, 'owner.json'), 'file'), JSON.stringify({ pid: process.pid, hostname: hostname(), startedAt: new Date().toISOString() }), { flag: 'wx' }); return await action(); }
+    finally { rmSync(storagePath(this.root, lock, 'directory'), { recursive: true, force: true }); }
   }
   lockStatus(name) {
     const lock = sourcePath(this.root, join(this.local(name), '.update-lock'));
@@ -380,29 +394,36 @@ export class ToolManager {
     return this.updateLocked(name);
   }); }
   async update(name) { this.preflight([name]); return this.withLock(name, async () => { this.migrate(name); return this.updateLocked(name); }); }
-  commitState(name, temporary) { renameSync(temporary, join(this.local(name), 'CURRENT.json')); }
+  commitState(name, temporary) {
+    const { local } = this.storage(name);
+    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 { local } = this.storage(name);
+    const target = storagePath(this.root, join(local, 'versions', `${release.version}-${this.target}`), 'directory');
     let installed;
     try { installed = this.check(name); } catch { /* Ausente ou quebrado: reparar em staging. */ }
     if (installed?.version === release.version) { this.launchers(name); return { ...installed, changed: false }; }
-    const local = this.local(name); mkdirSync(join(local, 'versions'), { recursive: true });
-    const stage = mkdtempSync(join(local, '.stage-')); const target = join(local, 'versions', `${release.version}-${this.target}`);
-    const temporary = join(local, `CURRENT.${process.pid}.${Date.now()}.json`); let previous; let moved = false;
+    mkdirSync(storagePath(this.root, join(local, 'versions'), 'directory'), { recursive: true });
+    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);
+      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);
       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() };
-      writeFileSync(temporary, `${JSON.stringify(info, null, 2)}\n`);
+      writeFileSync(storagePath(this.root, temporary, 'file'), `${JSON.stringify(info, null, 2)}\n`, { flag: 'wx' });
       this.launchers(name);
-      if (existsSync(target)) { previous = `${target}.previous-${process.pid}-${Date.now()}`; renameSync(target, previous); }
-      try { renameSync(stage, target); moved = true; this.commitState(name, temporary); }
-      catch (error) { if (moved) rmSync(target, { recursive: true, force: true }); if (previous) renameSync(previous, target); throw error; }
+      if (existsSync(target)) { previous = storagePath(this.root, `${target}.previous-${randomUUID()}`, 'directory'); renameSync(storagePath(this.root, target, 'directory'), previous); }
+      try { renameSync(storagePath(this.root, stage, 'directory'), storagePath(this.root, target, 'directory')); moved = true; this.commitState(name, temporary); }
+      catch (error) { if (moved) rmSync(storagePath(this.root, target, 'directory'), { recursive: true, force: true }); if (previous) renameSync(storagePath(this.root, previous, 'directory'), storagePath(this.root, target, 'directory')); throw error; }
       return { ...info, layout: 'local', prefix: target, changed: true };
-    } finally { rmSync(stage, { recursive: true, force: true }); rmSync(temporary, { force: 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); }
 }

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

@@ -232,6 +232,87 @@ test('falha ao gravar CURRENT restaura o target anterior e o pacote em uso', asy
   assert.equal(manager.check('test-tool').version, '1.0.0'); assert.ok(!existsSync(join(local, '.update-lock')));
 });
 
+test('versions simbolico existente ou quebrado e recusado antes de baixar ou escrever', async t => {
+  for (const broken of [false, true]) await t.test(broken ? 'broken' : 'existing', async subtest => {
+    const { root, manager, state, local } = fixture(subtest);
+    const outside = join(root, 'outside'); mkdirSync(outside);
+    writeFileSync(join(outside, 'keep.txt'), 'preservado'); mkdirSync(local);
+    if (!createSymlink(subtest, broken ? join(outside, 'missing') : outside, join(local, 'versions'), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    for (const action of ['install', 'update']) await assert.rejects(manager[action]('test-tool'), /nao pode ser um link/);
+    assert.equal(state.fetches, 0); assert.equal(state.installs, 0);
+    assert.deepEqual(readdirSync(outside), ['keep.txt']);
+    assert.equal(readFileSync(join(outside, 'keep.txt'), 'utf8'), 'preservado');
+    assert.equal(existsSync(join(local, 'CURRENT.json')), false);
+    assert.equal(existsSync(join(local, '.update-lock')), false);
+  });
+});
+
+test('recibo CURRENT e destino de versao simbolicos nao sao seguidos nem substituidos', async t => {
+  for (const kind of ['current', 'target', 'broken-target']) await t.test(kind, async subtest => {
+    const { root, manager, state, local } = fixture(subtest); await manager.install('test-tool');
+    const receipt = readFileSync(join(local, 'CURRENT.json'));
+    const outside = join(root, 'outside'); mkdirSync(outside); writeFileSync(join(outside, 'keep.txt'), 'preservado');
+    if (kind === 'current') {
+      writeFileSync(join(outside, 'CURRENT.json'), receipt); rmSync(join(local, 'CURRENT.json'));
+      if (!createSymlink(subtest, join(outside, 'CURRENT.json'), join(local, 'CURRENT.json'))) return;
+      assert.throws(() => manager.check('test-tool'), /nao pode ser um link/);
+    } else {
+      state.version = '2.0.0';
+      if (!createSymlink(subtest, kind === 'target' ? outside : join(outside, 'missing'), join(local, 'versions', `2.0.0-${platformKey()}`), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    }
+    const before = readdirSync(outside), installs = state.installs;
+    await assert.rejects(manager.update('test-tool'), /nao pode ser um link/);
+    assert.equal(state.installs, installs); assert.deepEqual(readdirSync(outside), before);
+    assert.equal(readFileSync(join(outside, 'keep.txt'), 'utf8'), 'preservado');
+    assert.deepEqual(readFileSync(kind === 'current' ? join(outside, 'CURRENT.json') : join(local, 'CURRENT.json')), receipt);
+  });
+});
+
+test('troca de versions durante fetch ou install nao escapa da arvore local', async t => {
+  for (const phase of ['fetch', 'install']) await t.test(phase, async subtest => {
+    const { root, manager, state, local } = fixture(subtest); await manager.install('test-tool');
+    const receipt = readFileSync(join(local, 'CURRENT.json')); state.version = '2.0.0';
+    const outside = join(root, 'outside'); mkdirSync(outside);
+    const probe = join(local, 'symlink-probe');
+    if (!createSymlink(subtest, outside, probe, process.platform === 'win32' ? 'junction' : 'dir')) return;
+    unlinkSync(probe);
+    const versions = join(local, 'versions'), kept = join(local, 'versions-kept'); let linked = false;
+    const replace = () => {
+      renameSync(versions, kept);
+      symlinkSync(outside, versions, process.platform === 'win32' ? 'junction' : 'dir'); linked = true;
+    };
+    if (phase === 'fetch') manager.fetchRelease = async () => { replace(); return release('2.0.0'); };
+    else manager.installPackage = (prefix, name, version) => { packageFiles(prefix, name, version); replace(); };
+    try {
+      await assert.rejects(manager.update('test-tool'), /nao pode ser um link/);
+      assert.deepEqual(readdirSync(outside), []); assert.deepEqual(readFileSync(join(local, 'CURRENT.json')), receipt);
+    } finally { if (linked) { unlinkSync(versions); renameSync(kept, versions); } }
+    assert.equal(manager.check('test-tool').version, '1.0.0');
+    assert.equal(existsSync(join(local, '.update-lock')), false);
+  });
+});
+
+test('migracao recusa links de versions antigo e cache compartilhado sem mover dados', async t => {
+  for (const kind of ['legacy-versions', 'cache']) await t.test(kind, async subtest => {
+    const { root, manager, state } = fixture(subtest);
+    const home = join(root, '.pbai4devs/tools'), legacy = join(home, 'test-tool');
+    const outside = join(root, 'outside'); mkdirSync(outside); writeFileSync(join(outside, 'keep.txt'), 'preservado');
+    if (kind === 'legacy-versions') {
+      writeFileSync(join(legacy, 'CURRENT.json'), JSON.stringify({ name: 'test-tool', version: '1.0.0', platform: platformKey() }));
+      if (!createSymlink(subtest, outside, join(legacy, 'versions'), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    } else {
+      mkdirSync(join(home, 'npm-cache')); writeFileSync(join(home, 'npm-cache/keep.txt'), 'cache antigo');
+      if (!createSymlink(subtest, outside, join(home, '.cache'), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    }
+    await assert.rejects(manager.install('test-tool'), /nao pode ser um link/);
+    assert.equal(state.fetches, 0); assert.equal(state.installs, 0);
+    assert.deepEqual(readdirSync(outside), ['keep.txt']);
+    assert.equal(readFileSync(join(outside, 'keep.txt'), 'utf8'), 'preservado');
+    if (kind === 'legacy-versions') assert.ok(existsSync(join(legacy, 'CURRENT.json')));
+    else assert.equal(readFileSync(join(home, 'npm-cache/keep.txt'), 'utf8'), 'cache antigo');
+  });
+});
+
 test('duas atualizacoes nao disputam a mesma ferramenta nem apagam lock alheio', async t => {
   const { manager, state, local } = fixture(t); let enter; let proceed;
   const entered = new Promise(resolve => { enter = resolve; });

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -12,6 +12,9 @@ node --test .pbai4devs/scripts/sincronizar-agentes/tests/TEST.mjs
 
 `--check` só confere; a execução normal atualiza os recursos. `--force` salva
 conflitos em `.agent-tests/` antes de reparar os caminhos gerenciados.
+Recursos nativos humanos e seus links permanecem intactos, inclusive com
+`--force`. O retorno inclui `preserved`; esses caminhos não contam como
+derivados pendentes nem passam a pertencer ao kit.
 
 Metadados vêm da fonte ou do YAML nativo declarado no manifesto. Regras exigem
 `trigger` válido; `glob` exige `globs`. Origens nativas precisam pertencer ao