@pathbit/agentdevkit 0.0.6 → 0.0.8

package/.pbai4devs/scripts/lib/gitignore.mjs

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
@@ -63,6 +63,7 @@ export function renderClientIgnore(template, settings = {}) {
 
 const localStat = file => { try { return lstatSync(file); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; } };
 const localRead = file => localStat(file) ? readFileSync(file, 'utf8') : null;
+const localMode = file => { const item = localStat(file); return item ? item.mode & 0o777 : null; };
 const portable = path => path.split(sep).join('/');
 
 function canonicalExisting(path) {
@@ -114,6 +115,107 @@ function rootProbes(root, roots) {
   return roots.filter(path => { const item = localStat(join(root, path)); return !item || item.isDirectory(); }).map(path => `${path}/.agentdevkit-ignore-probe`);
 }
 
+function artifactPolicy(templateFile) {
+  const adjacent = join(dirname(templateFile), 'agents.ignore');
+  const source = checkedLocalPath(localStat(adjacent) ? adjacent : fileURLToPath(new URL('../../templates/gitignore/agents.ignore', import.meta.url)));
+  const content = readFileSync(source, 'utf8');
+  const section = content.split(/^## Resultados e arquivos temporarios\r?$/m)[1]?.split(/^## /m)[0];
+  const patterns = section?.split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#'));
+  if (!patterns?.length || patterns.some(pattern => !pattern.startsWith('**/') || /[!\\\x00-\x1f]/.test(pattern) || pattern.split('/').includes('..'))) throw new Error('Secao de artefatos invalida em agents.ignore.');
+  return patterns;
+}
+
+function artifactProbes(root, patterns) {
+  const probes = new Set();
+  for (const pattern of patterns) {
+    const stem = pattern.slice(3).replace(/\/$/, '').replace(/\[([^\]]+)\]/g, (_match, letters) => letters[0]).replace(/\?/g, 'x');
+    const names = stem.includes('*') ? ['', '-mcp', '-report', '-cache', '-agentdevkit'].map(suffix => stem.replace(/\*/g, suffix)) : [stem];
+    for (const name of names) for (const variant of new Set([name, name.toLowerCase()])) {
+      const leaves = stem.includes('*') ? ['.agentdevkit-artifact-probe', '.cache/.agentdevkit-artifact-probe'] : ['.agentdevkit-artifact-probe'];
+      for (const leaf of leaves) for (const path of [`${variant}/${leaf}`, `.agentdevkit-ignore-probes/${variant}/${leaf}`]) {
+        let parent = root, safe = true;
+        for (const part of path.split('/').slice(0, -1)) {
+          parent = join(parent, part); const item = localStat(parent);
+          if (item && !item.isDirectory()) { safe = false; break; }
+        }
+        if (safe) probes.add(path);
+      }
+    }
+  }
+  return [...probes];
+}
+
+const matchesComponent = (part, pattern) => posix.matchesGlob(`x${part}`, `x${pattern.replace(/[{}()]/g, '\\$&')}`);
+
+function matchesParts(parts, pattern) {
+  const cache = new Map();
+  function match(part, glob) {
+    const key = `${part}:${glob}`; if (cache.has(key)) return cache.get(key);
+    const expected = pattern[glob];
+    const result = glob === pattern.length ? part === parts.length
+      : expected === '**' ? match(part, glob + 1) || part < parts.length && match(part + 1, glob)
+        : part < parts.length && matchesComponent(parts[part], expected) && match(part + 1, glob + 1);
+    cache.set(key, result); return result;
+  }
+  return match(0, 0);
+}
+
+function artifactPath(path, patterns, directory = false) {
+  const parts = path.split('/');
+  return patterns.some(pattern => {
+    const rule = pattern.slice(3).replace(/\/$/, '');
+    return parts.some((part, index) => (index < parts.length - 1 || directory || !pattern.endsWith('/'))
+      && (rule.includes('/') ? matchesParts(parts.slice(0, index + 1), ['**', ...rule.split('/')])
+        : matchesComponent(part, rule)));
+  });
+}
+
+function visibleArtifactProbes(root, location, patterns) {
+  const listed = gitCommand(location.top, ['--literal-pathspecs', '-c', 'core.excludesFile=', 'ls-files', '--cached', '--others', '--exclude-standard', '-z', '--', location.prefix ? `${location.prefix}/` : '.']);
+  if (listed.error || listed.status !== 0) throw new Error(listed.error?.message || listed.stderr || 'Falha ao conferir artefatos existentes.');
+  const paths = listed.stdout.split('\0').filter(Boolean), prefix = location.prefix ? `${location.prefix}/` : '';
+  const probes = new Set(paths.filter(path => path.startsWith(prefix)).map(path => path.slice(prefix.length)).filter(path => artifactPath(path, patterns)));
+  const ignores = new Set(paths.filter(path => path.startsWith(prefix) && (path === '.gitignore' || path.endsWith('/.gitignore'))));
+  let ancestor = root;
+  while (true) {
+    ignores.add(portable(relative(location.top, join(ancestor, '.gitignore'))));
+    if (ancestor === location.top) break;
+    ancestor = dirname(ancestor);
+  }
+  for (const path of ignores) {
+    const file = join(location.top, path), item = localStat(file);
+    if (!item?.isFile() || item.isSymbolicLink()) continue;
+    // Git resolves precedence; these literals only add witnesses for named exceptions.
+    for (const line of readFileSync(checkedLocalPath(file), 'utf8').split(/\r?\n/)) {
+      if (!line.startsWith('!') || line.length === 1) continue;
+      const rule = line.slice(1).replace(/(?<!\\) +$/, ''), directory = rule.endsWith('/') || rule.endsWith('/**');
+      const literal = rule.replace(/(?:\/\*\*)+\/?$/, '').replace(/\/$/, '').replace(/^\//, '');
+      if (/(^|[^\\])[*?\[]/.test(literal)) continue;
+      const ruleBase = !rule.startsWith('/') && !literal.includes('/') && relative(dirname(file), root).split(sep)[0] !== '..' ? root : dirname(file);
+      const candidate = portable(relative(root, resolve(ruleBase, literal.replace(/\\(.)/g, '$1'))));
+      if (!candidate || candidate === '..' || candidate.startsWith('../') || !artifactPath(candidate, patterns, directory)) continue;
+      probes.add(checkedOutput(directory ? `${candidate}/.agentdevkit-artifact-probe` : candidate));
+    }
+  }
+  return [...probes];
+}
+
+function localIgnoreSource(location, source) {
+  const path = resolve(location.top, source);
+  if (path === location.exclude) return true;
+  const inside = relative(location.top, path);
+  return basename(path) === '.gitignore' && !isAbsolute(inside) && inside !== '..' && !inside.startsWith(`..${sep}`);
+}
+
+function ignoreMatches(location, probes) {
+  const paths = probes.map(path => location.prefix ? `${location.prefix}/${path}` : path);
+  const result = gitCommand(location.top, ['-c', 'core.excludesFile=', 'check-ignore', '--verbose', '--no-index', '--stdin', '-z'], paths.join('\0') + '\0');
+  if (result.error || ![0, 1].includes(result.status)) throw new Error(result.error?.message || result.stderr || 'Falha ao conferir exclusoes Git.');
+  const values = result.stdout.split('\0'), matches = new Map();
+  for (let index = 0; index + 3 < values.length; index += 4) matches.set(values[index + 3], { source: values[index], line: Number(values[index + 1]), pattern: values[index + 2] });
+  return { paths, matches };
+}
+
 function localRoot(value) {
   const missing = []; let parent = resolve(value);
   while (!localStat(parent)) { missing.unshift(parent.slice(dirname(parent).length + 1)); parent = dirname(parent); }
@@ -128,6 +230,7 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const localTemplate = join(root, '.pbai4devs/templates/gitignore/local.ignore');
   const templateFile = checkedLocalPath(templateRoot ? join(templateRoot, '.pbai4devs/templates/gitignore/local.ignore') : localStat(localTemplate) ? localTemplate : fileURLToPath(new URL('../../templates/gitignore/local.ignore', import.meta.url)));
   const template = readFileSync(templateFile, 'utf8');
+  const artifacts = artifactPolicy(templateFile);
   if (template.split('{{OUTPUTS}}').length !== 2) throw new Error('local.ignore exige um unico {{OUTPUTS}}.');
   if (template.split('{{ROOTS}}').length > 2) throw new Error('local.ignore permite um unico {{ROOTS}}.');
   const localPolicy = join(templateRoot || root, '.pbai4devs/templates/clients/ADAPTERS.json');
@@ -152,24 +255,26 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   }
   const id = createHash('sha256').update(root).digest('hex').slice(0, 16);
   const first = `# BEGIN AGENTDEVKIT LOCAL ${id}`, last = `# END AGENTDEVKIT LOCAL ${id}`;
-  const fixed = template.replace('{{ROOTS}}', roots.map(path => `/${path}/`).join('\n')).replace('{{OUTPUTS}}', paths.filter(path => !roots.some(root => path === root || path.startsWith(root + '/'))).map(path => `/${escapePattern(path)}`).join('\n'));
+  const fixed = template.replace('{{ROOTS}}', roots.map(path => `/${path}/`).join('\n')).replace('{{OUTPUTS}}', paths.filter(path => !roots.some(root => path === root || path.startsWith(root + '/'))).map(path => `/${escapePattern(path)}`).join('\n'))
+    + '\n# Resultados e arquivos temporarios\n' + artifacts.map(pattern => `/${pattern}`).join('\n') + '\n';
   const body = fixed.split(/\r?\n/).map(line => location?.prefix && line.startsWith('/') ? `/${escapePattern(location.prefix)}${line}` : line).join('\n');
   const target = location?.exclude ?? checkedLocalPath(join(root, '.gitignore'));
   const before = localRead(target), after = localBlock(before, first, last, body);
-  const edits = before === after ? [] : [{ path: target, before, after }];
+  const edits = before === after ? [] : [{ path: target, before, after, beforeMode: localMode(target) }];
   const probes = [...paths, ...rootProbes(root, roots)];
+  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
   const wanted = new Set(probes.map(path => location?.prefix ? `${location.prefix}/${path}` : path));
   if (location && !before?.includes(first) && !localRead(join(root, '.gitignore'))?.includes(first)) {
-    const ignored = gitCommand(location.top, ['check-ignore', '--no-index', '--stdin', '-z'], [...wanted].join('\0') + '\0');
-    if (!ignored.error && [0, 1].includes(ignored.status) && ignored.stdout.split('\0').filter(Boolean).length === wanted.size) edits.length = 0;
+    const ignored = ignoreMatches(location, [...probes, ...artifactPaths]);
+    if (ignored.paths.every(path => { const match = ignored.matches.get(path); return match && !match.pattern.startsWith('!') && localIgnoreSource(location, match.source); })) edits.length = 0;
   }
   if (location) {
     const fallback = checkedLocalPath(join(root, '.gitignore'));
     const old = localRead(fallback), next = localBlock(old, first, last, null);
-    if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next });
+    if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next, beforeMode: localMode(fallback) });
   }
   const tracked = location ? gitCommand(location.top, ['ls-files', '-z']).stdout.split('\0').filter(path => wanted.has(path)).map(path => location.prefix ? path.slice(location.prefix.length + 1) : path) : [];
-  return { root, status: location ? 'git' : 'fallback', location, paths, roots, edits, trackedOutputs: tracked, first, last };
+  return { root, status: location ? 'git' : 'fallback', location, paths, roots, artifactPatterns: artifacts, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
 }
 
 export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
@@ -185,19 +290,17 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
     if (createHash('sha256').update(block).digest('hex') !== item.sha256) throw new Error('Bloco de ignore mudou antes da verificacao.');
     return { ...item, path };
   });
-  if (plan.location && plan.paths.length) {
-    const probes = [...plan.paths, ...rootProbes(plan.root, plan.roots || [])];
-    const relativePaths = probes.map(path => plan.location.prefix ? `${plan.location.prefix}/${path}` : path);
-    const result = gitCommand(plan.location.top, ['check-ignore', '--verbose', '--no-index', '--stdin', '-z'], relativePaths.join('\0') + '\0');
-    if (result.error || ![0, 1].includes(result.status)) throw new Error(result.error?.message || result.stderr || 'Falha ao conferir exclusoes Git.');
-    const values = result.stdout.split('\0'), matches = new Map();
-    for (let index = 0; index + 3 < values.length; index += 4) matches.set(values[index + 3], { source: values[index], line: Number(values[index + 1]), pattern: values[index + 2] });
+  if (plan.location && (plan.paths.length || plan.artifactProbes?.length)) {
+    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || []),
+      ...(plan.artifactPatterns ? visibleArtifactProbes(plan.root, plan.location, plan.artifactPatterns) : [])])];
+    const { paths: relativePaths, matches } = ignoreMatches(plan.location, probes);
     for (let index = 0; index < relativePaths.length; index++) {
       const match = matches.get(relativePaths[index]);
       const negative = match?.pattern.startsWith('!');
-      const humanOverride = negative && /(?:^|[\\/])\.gitignore$/.test(match.source);
+      const local = match && localIgnoreSource(plan.location, match.source);
+      const humanOverride = negative && local && /(?:^|[\\/])\.gitignore$/.test(match.source);
       const replaced = negative && replacements.some(item => item.path === canonicalExisting(resolve(plan.location.top, match.source)) && match.line >= item.firstLine && match.line <= item.lastLine);
-      if (!replaced && ((!plan.edits.length && (!match || negative)) || humanOverride)) missing.push(probes[index]);
+      if (!replaced && ((!plan.edits.length && (!match || negative || !local)) || humanOverride)) missing.push(probes[index]);
     }
   }
   return { ok: plan.edits.length === 0 && missing.length === 0 && plan.trackedOutputs.length === 0, status: plan.status, missing, trackedOutputs: plan.trackedOutputs, changed: plan.edits.length };
@@ -206,28 +309,42 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
 export function assertLocalIgnoreUnchanged(plan) {
   for (const edit of plan.edits) {
     checkedLocalPath(edit.path);
-    if (localRead(edit.path) !== edit.before) throw new Error(`Exclusao alterada apos planejar: ${edit.path}`);
+    if (localRead(edit.path) !== edit.before || Object.hasOwn(edit, 'beforeMode') && localMode(edit.path) !== edit.beforeMode) throw new Error(`Exclusao alterada apos planejar: ${edit.path}`);
   }
 }
 
+function atomicLocalWrite(path, content, mode, published) {
+  const temporary = `${path}.agentdevkit-${randomUUID()}`;
+  try {
+    writeFileSync(temporary, content, { flag: 'wx' });
+    if (mode !== null && mode !== undefined) chmodSync(temporary, mode);
+    const writtenMode = localMode(temporary);
+    renameSync(temporary, path);
+    published?.(writtenMode);
+  } finally { rmSync(temporary, { force: true }); }
+}
+
 export function applyLocalIgnore(plan) {
   assertLocalIgnoreUnchanged(plan);
+  const before = checkLocalIgnore(plan);
+  if (before.missing.length) throw new Error(`Regras humanas reabrem derivados locais: ${before.missing.join(', ')}`);
   const written = [];
   try {
     for (const edit of plan.edits) {
       mkdirSync(dirname(edit.path), { recursive: true });
-      const temporary = `${edit.path}.agentdevkit-${randomUUID()}`;
-      try { writeFileSync(temporary, edit.after, { flag: 'wx' }); renameSync(temporary, edit.path); }
-      finally { rmSync(temporary, { force: true }); }
-      written.push(edit);
+      atomicLocalWrite(edit.path, edit.after, edit.beforeMode, mode => written.push({ edit, mode }));
     }
     const verified = checkLocalIgnore({ ...plan, edits: [], trackedOutputs: [] });
     if (verified.missing.length) throw new Error(`Regras humanas reabrem derivados locais: ${verified.missing.join(', ')}`);
   } catch (error) {
-    for (const edit of written.reverse()) {
-      if (localRead(edit.path) !== edit.after) continue;
-      if (edit.before === null) rmSync(edit.path, { force: true }); else writeFileSync(edit.path, edit.before);
+    const rollbackErrors = [];
+    for (const { edit, mode } of written.reverse()) {
+      try {
+        if (localRead(edit.path) !== edit.after || localMode(edit.path) !== mode) continue;
+        if (edit.before === null) rmSync(edit.path, { force: true }); else atomicLocalWrite(edit.path, edit.before, edit.beforeMode);
+      } catch (failure) { rollbackErrors.push(failure); }
     }
+    if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error });
     throw error;
   }
   return { status: plan.status, changed: plan.edits.length, trackedOutputs: plan.trackedOutputs };

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; });