@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/scripts/lib/catalog.mjs

@@ -0,0 +1,170 @@
+// Índices derivados das fontes versionadas; não lê instalações ou caches locais.
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join, posix, resolve } from 'node:path';
+import { loadCatalog as loadTools, toolActions } from '../preparar-ferramentas/SCRIPT.mjs';
+import { validateCatalog as validateExternalCatalog } from '../gerenciar-skills-externas/SCRIPT.mjs';
+import { requireNode } from './runtime.mjs';
+import { isGeneratedOutput } from './gitignore.mjs';
+import { parseScriptConfig } from './script-config.mjs';
+
+const kinds = { skills: 'SKILL.md', agents: 'AGENT.md', commands: 'COMMAND.md', rules: 'RULE.md', templates: 'TEMPLATE.md' };
+const excluded = new Set(['.git', 'node_modules', '.local', '.cache', 'opencode-loop']);
+const generated = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']);
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const sorted = values => [...new Set(values)].sort(compare);
+const fail = message => { throw new Error(message); };
+const stat = file => { try { return lstatSync(file); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; } };
+
+function scanner(root) {
+  const absolute = path => join(root, ...path.split('/'));
+  function safe(path, required = false) {
+    if (typeof path !== 'string' || !path || /^[A-Za-z]:/.test(path) || /[|\\\x00-\x1f\x7f]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) fail(`Caminho de catalogo invalido: ${path}`);
+    let current = root;
+    for (const part of path.split('/')) {
+      if (stat(current)?.isDirectory() && readdirSync(current).some(name => name.toLowerCase() === part.toLowerCase() && name !== part)) fail(`Caminhos diferem somente por maiusculas/minusculas: ${path}`);
+      current = join(current, part);
+      if (stat(current)?.isSymbolicLink()) fail(`Link simbolico no catalogo: ${path}`);
+    }
+    if (required && !stat(current)) fail(`Referencia ausente no catalogo: ${path}`);
+    return current;
+  }
+  function walk(path) {
+    const info = stat(safe(path));
+    if (!info) return [];
+    if (!info.isDirectory()) fail(`Pasta de catalogo invalida: ${path}`);
+    const result = [];
+    for (const name of readdirSync(absolute(path)).sort(compare)) {
+      const child = `${path}/${name}`, item = stat(safe(child));
+      if (excluded.has(name.toLowerCase()) || isGeneratedOutput(child, item.isDirectory()) || (path.startsWith('.pbai4devs/tools/') && ['versions', 'bin'].includes(name))) continue;
+      if (item.isDirectory()) result.push(...walk(child));
+      else if (item.isFile()) result.push(child);
+      else fail(`Tipo de arquivo nao suportado no catalogo: ${child}`);
+    }
+    return result;
+  }
+  const read = path => readFileSync(safe(path, true), 'utf8').replace(/\r\n?/g, '\n');
+  const json = path => { try { return JSON.parse(read(path)); } catch (error) { fail(`JSON invalido: ${path}: ${error.message}`); } };
+  return { absolute, safe, walk, read, json };
+}
+
+function metadata(text, path, required = true, fields = ['name', 'description']) {
+  const lines = text.split('\n');
+  if (lines[0] !== '---') { if (required) fail(`Frontmatter YAML ausente: ${path}`); return {}; }
+  const end = lines.indexOf('---', 1);
+  if (end < 0) fail(`Frontmatter YAML sem fechamento: ${path}`);
+  const result = {};
+  for (let i = 1; i < end; i++) {
+    const match = lines[i].match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+    if (!match || !fields.includes(match[1])) continue;
+    const key = match[1]; let value = match[2].trim();
+    if (Object.hasOwn(result, key)) fail(`Metadado duplicado ${key}: ${path}`);
+    if (/^[>|][-+]?$/.test(value)) {
+      const block = [];
+      while (i + 1 < end && (/^\s/.test(lines[i + 1]) || !lines[i + 1])) block.push(lines[++i].trim());
+      value = block.join(' ');
+    } else if (value.startsWith('"')) {
+      try { value = JSON.parse(value); } catch { fail(`Metadado invalido ${key}: ${path}`); }
+    } else if (value.startsWith("'")) {
+      if (!value.endsWith("'")) fail(`Metadado invalido ${key}: ${path}`);
+      value = value.slice(1, -1).replace(/''/g, "'");
+    } else if (/^[\[{]|^(?:null|true|false)$/.test(value)) fail(`Metadado deve ser texto ${key}: ${path}`);
+    if (typeof value !== 'string' || !value.trim()) fail(`Metadado vazio ${key}: ${path}`);
+    result[key] = value.replace(/\s+/g, ' ').trim();
+  }
+  return result;
+}
+
+function ruleScope(meta, path) {
+  if (!['always_on', 'model_decision', 'glob', 'manual'].includes(meta.trigger)) fail(`Trigger de regra ausente ou invalido: ${path}`);
+  if (meta.globs && meta.glob && meta.globs !== meta.glob) fail(`Glob e globs conflitantes: ${path}`);
+  const globs = meta.globs || meta.glob;
+  if (meta.trigger === 'glob' && !globs) fail(`Regra glob exige globs: ${path}`);
+  return { trigger: meta.trigger, ...(globs ? { globs } : {}) };
+}
+
+function localLinks(text, path, scan) {
+  const clean = text.replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1\s*$/gm, '');
+  const raw = [...clean.matchAll(/\]\((<[^>]+>|[^\s)]+)(?:\s+["'][^\n]*?["'])?\)/g)].map(match => match[1]);
+  raw.push(...[...clean.matchAll(/^\s*\[[^\]]+\]:\s*(<[^>]+>|\S+)/gm)].map(match => match[1]));
+  const references = [];
+  for (let href of raw) {
+    href = href.replace(/^<|>$/g, '');
+    if (!href || href.startsWith('#') || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(href)) continue;
+    let location;
+    try { location = decodeURIComponent(href.split(/[?#]/)[0]); } catch { fail(`Link invalido em ${path}: ${href}`); }
+    if (!location) continue;
+    if (location.startsWith('/') || location.includes('\\')) fail(`Link deve ser relativo em ${path}: ${href}`);
+    const target = posix.normalize(posix.join(posix.dirname(path), location)).replace(/\/+$/, '');
+    if (!generated.has(target)) scan.safe(target, true);
+    references.push(target);
+  }
+  return sorted(references);
+}
+
+function registry(paths) {
+  const values = sorted(paths);
+  return '{\n  "entries": [\n' + values.map((path, index) => `    {"path": ${JSON.stringify(path)}}${index < values.length - 1 ? ',' : ''}\n`).join('') + '  ]\n}\n';
+}
+
+export function buildCatalog(root) {
+  requireNode(); root = realpathSync(resolve(root));
+  const scan = scanner(root);
+  const catalog = { schemaVersion: 1, skills: [], agents: [], commands: [], rules: [], templates: [], tools: [], scripts: [], externalSkills: [] };
+  for (const [kind, principal] of Object.entries(kinds)) {
+    const files = scan.walk(`.pbai4devs/${kind}`);
+    const mains = files.filter(path => posix.basename(path) === principal);
+    for (const path of mains) {
+      const folder = posix.dirname(path);
+      const text = scan.read(path), meta = metadata(text, path, true, kind === 'rules' ? ['name', 'description', 'trigger', 'globs', 'glob'] : undefined);
+      const title = text.match(/^# (.+)$/m)?.[1];
+      if (!title) fail(`Titulo ausente: ${path}`);
+      if (!meta.description) fail(`Descricao ausente: ${path}`);
+      const entry = { id: folder.slice(`.pbai4devs/${kind}/`.length), name: meta.name || posix.basename(folder), description: meta.description, path, assets: files.filter(file => file !== path && file.startsWith(folder + '/')) };
+      if (kind === 'rules') Object.assign(entry, ruleScope(meta, path));
+      if (kind === 'commands') entry.references = localLinks(text, path, scan);
+      catalog[kind].push(entry);
+    }
+  }
+  const tools = loadTools(root);
+  for (const name of Object.keys(tools).sort(compare)) {
+    const config = tools[name];
+    const path = `.pbai4devs/tools/${name}/TOOL.json`;
+    const entryPath = `.pbai4devs/tools/${name}/${config.scripts.entry}`;
+    if (!stat(scan.safe(entryPath, true))?.isFile()) fail(`Script de ferramenta nao e arquivo: ${entryPath}`);
+    const folder = posix.dirname(path);
+    const assets = scan.walk(folder).filter(file => file !== path && !file.slice(folder.length + 1).match(/^(?:versions|bin)\/|^(?:CURRENT\.json|package-lock\.json)$/));
+    catalog.tools.push({ id: name, name: config.name, description: config.description, path, assets, group: config.group, entry: entryPath, actions: toolActions(name, config) });
+  }
+  const scriptFiles = scan.walk('.pbai4devs/scripts');
+  const sharedAssets = scriptFiles.filter(path => path.startsWith('.pbai4devs/scripts/lib/'));
+  const directories = sorted(scriptFiles.filter(path => /^\.pbai4devs\/scripts\/[^/]+\/SCRIPT\.(?:mjs|cjs|js|conf)$/.test(path)).map(path => posix.dirname(path)));
+  for (const folder of directories) {
+    const name = posix.basename(folder);
+    const config = `${folder}/SCRIPT.conf`;
+    const configInfo = stat(scan.safe(config)); const hasConfig = Boolean(configInfo);
+    if (hasConfig && !configInfo.isFile()) fail(`SCRIPT.conf deve ser um arquivo: ${config}`);
+    const executor = hasConfig ? parseScriptConfig(scan.read(config)) : 'node';
+    const path = executor === 'playwright-mcp' ? `${folder}/SCRIPT.js`
+      : ['mjs', 'cjs', 'js'].map(extension => `${folder}/SCRIPT.${extension}`).find(candidate => stat(scan.safe(candidate))) || `${folder}/SCRIPT.mjs`;
+    if (!stat(scan.safe(path, true))?.isFile()) fail(`Entrada de script nao e arquivo: ${path}`);
+    const readme = `${folder}/README.md`;
+    const meta = stat(scan.safe(readme))?.isFile() ? metadata(scan.read(readme), readme, false) : {};
+    const assets = sorted([...scriptFiles.filter(file => file !== path && file.startsWith(folder + '/')), ...sharedAssets]);
+    catalog.scripts.push({ id: name, name, description: meta.description || `Automação ${name}.`, path, assets, support: { modules: sharedAssets.filter(file => file.endsWith('.mjs')), tests: assets.filter(file => /\/tests\//.test(file) && !/\/SMOKE[^/]*\.mjs$/.test(file)), smokes: assets.filter(file => /\/SMOKE[^/]*\.mjs$/.test(file)) }, executor, argv: executor === 'node' ? ['node', path] : [], ...(hasConfig ? { configuration: config } : {}) });
+  }
+  const externalFile = '.pbai4devs/external-skills/CATALOG.json';
+  if (stat(scan.safe(externalFile))) {
+    const external = validateExternalCatalog(scan.json(externalFile));
+    for (const item of external.skills) {
+      const manager = '.pbai4devs/scripts/gerenciar-skills-externas/SCRIPT.mjs';
+      const actions = stat(scan.safe(manager))?.isFile() ? Object.fromEntries(['discover', 'install', 'check', 'update', 'read'].map(action => [action, { executor: 'node', argv: ['node', manager, action, item.id] }])) : null;
+      catalog.externalSkills.push({ id: item.id, name: item.name, description: item.use, path: externalFile, assets: [], repository: item.repository, commit: item.commit, upstreamPath: item.path, license: item.license, status: item.status, ...(actions ? { actions } : {}), ...(item.notes ? { notes: item.notes } : {}), ...(item.licenseSource ? { licenseSource: item.licenseSource } : {}) });
+    }
+  }
+  for (const kind of Object.keys(catalog).filter(key => Array.isArray(catalog[key]))) catalog[kind].sort((a, b) => compare(a.id, b.id));
+  const outputs = new Map([['.pbai4devs/catalog.json', JSON.stringify(catalog, null, 2) + '\n']]);
+  outputs.set('.pbai4devs/skills.json', registry(catalog.skills.map(entry => posix.dirname(entry.path))));
+  outputs.set('.pbai4devs/rules.json', registry(catalog.rules.map(entry => entry.path)));
+  outputs.set('.pbai4devs/agents.json', registry(catalog.agents.map(entry => entry.path)));
+  return { catalog, outputs };
+}

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

@@ -0,0 +1,348 @@
+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 { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// Atualiza apenas o bloco reservado; regras externas permanecem byte a byte.
+export const ignoreBegin = '# BEGIN AGENT IGNORE';
+export const ignoreEnd = '# END AGENT IGNORE';
+
+const outputDirectories = new Set(['.git', '.agent-tests', '.cache', 'node_modules', '__pycache__', 'opencode-loop', 'sessions', 'logs', 'testresults', 'test-results', 'blob-report', 'tmp', 'temp']);
+const localFiles = new Set(['auth.json', 'credentials.json', 'history.jsonl', '.ds_store', 'thumbs.db', 'desktop.ini']);
+
+// Mesmos nomes de saídas locais ignoradas; não exclui fixtures/cache nem arquivos .template.
+export function isGeneratedOutput(path, directory = false) {
+  const parts = path.replaceAll('\\', '/').split('/');
+  return parts.some((part, index) => {
+    const name = part.toLowerCase();
+    const folder = index < parts.length - 1 || directory;
+    const localFile = localFiles.has(name) || /\.(?:log|swp|swo)$|~$|^\._/.test(name) || /\.local\.(?:jsonc?|toml|ya?ml)$/.test(name);
+    const secretEnv = /^\.env(?:\.|$)/.test(name) && !/^\.env\.(?:example|sample|template|.*\.example)$/.test(part);
+    return /^\.playwright/.test(name) || (folder && (outputDirectories.has(name) || name.startsWith('playwright'))) || (!folder && (localFile || secretEnv));
+  });
+}
+
+export function validateIgnoreClients(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('clients.json deve conter um objeto.');
+  const names = new Set();
+  for (const [name, settings] of Object.entries(value)) {
+    if (!/^\.[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || ['.git', '.pbai4devs', '.agent-tests'].includes(name.toLowerCase()) || names.has(name.toLowerCase())) throw new Error(`Cliente .gitignore invalido: ${name}`);
+    names.add(name.toLowerCase());
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings) || Object.keys(settings).some(key => !['resources', 'allow'].includes(key))) throw new Error(`Configuracao .gitignore invalida: ${name}`);
+    if (settings.resources !== undefined && typeof settings.resources !== 'boolean') throw new Error(`resources deve ser booleano: ${name}`);
+    const allow = settings.allow === undefined ? [] : settings.allow;
+    if (!Array.isArray(allow) || new Set(allow).size !== allow.length) throw new Error(`allow deve ser uma lista sem duplicados: ${name}`);
+    for (const path of allow) {
+      if (typeof path !== 'string' || !path || /[\\:*?\[\]!#<>|\x00-\x1f\x7f]/.test(path) || path.trim() !== path || path.replace(/\/$/, '').split('/').some(part => !part || part === '.' || part === '..')) throw new Error(`Caminho allow deve ser relativo e literal: ${name}`);
+    }
+  }
+  return value;
+}
+
+export function renderClientIgnore(template, settings = {}) {
+  const token = '{{ALLOWLIST}}';
+  if (!template.includes(token)) return template;
+  if (template.split(token).length !== 2) throw new Error('agents.ignore exige um unico {{ALLOWLIST}}.');
+  const allowed = [...(settings.resources === false ? [] : ['skills/', 'agents/', 'commands/', 'rules/']), ...(settings.allow ?? [])];
+  const directories = allowed.filter(path => path.endsWith('/'));
+  const patterns = new Set();
+  for (const path of allowed) {
+    const directory = path.endsWith('/');
+    const parts = path.replace(/\/$/, '').split('/');
+    for (let end = 1; end < parts.length; end++) {
+      const ancestor = parts.slice(0, end).join('/') + '/';
+      patterns.add(`!/${ancestor}`);
+      if (!directories.some(value => ancestor.startsWith(value))) patterns.add(`/${ancestor}*`);
+    }
+    if (directory) patterns.add(`!/${parts.join('/')}/`);
+    else patterns.add(`!/${path}`);
+  }
+  return template.replace(token, [...patterns].join('\n'));
+}
+
+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 portable = path => path.split(sep).join('/');
+
+function canonicalExisting(path) {
+  if (typeof realpathSync.native === 'function') {
+    try { return realpathSync.native(path); }
+    catch (error) { if (!['ENOSYS', 'ENOTSUP', 'EINVAL'].includes(error.code)) throw error; }
+  }
+  return realpathSync(path);
+}
+
+function checkedLocalPath(file) {
+  let current = resolve(file);
+  while (true) {
+    if (localStat(current)?.isSymbolicLink()) throw new Error(`Link simbolico em exclusao local: ${file}`);
+    const parent = dirname(current); if (parent === current) break; current = parent;
+  }
+  const item = localStat(file);
+  if (item && !item.isFile()) throw new Error(`Exclusao local exige arquivo regular: ${file}`);
+  return file;
+}
+
+function localBlock(current, first, last, body) {
+  const text = current ?? '';
+  const begins = [...text.matchAll(new RegExp(`^${first}\\r?$`, 'gm'))];
+  const ends = [...text.matchAll(new RegExp(`^${last}\\r?$`, 'gm'))];
+  if (begins.length !== ends.length || begins.length > 1 || begins.length && begins[0].index > ends[0].index) throw new Error('Bloco de exclusao local invalido.');
+  const block = body === null ? '' : `${first}\n${body.trimEnd()}\n${last}\n`;
+  if (!begins.length) return block ? text + (text && !text.endsWith('\n') ? '\n' : '') + block : text;
+  const start = begins[0].index;
+  const offset = ends[0].index + ends[0][0].length;
+  const finish = offset + (text[offset] === '\n' ? 1 : 0);
+  return text.slice(0, start) + block + text.slice(finish);
+}
+
+function gitCommand(root, args, input) {
+  const env = { ...process.env };
+  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete env[key];
+  return spawnSync('git', [...(['ls-files', 'rm'].includes(args[0]) ? ['--literal-pathspecs'] : []), '-C', root, ...args], { input, encoding: 'utf8', env, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+}
+
+function checkedOutput(path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /[\\\x00-\x1f\x7f]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) throw new Error(`Saida local invalida: ${path}`);
+  return path;
+}
+
+function escapePattern(path) { return path.replace(/[\\!#*?\[\] ]/g, '\\$&'); }
+
+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 localRoot(value) {
+  const missing = []; let parent = resolve(value);
+  while (!localStat(parent)) { missing.unshift(parent.slice(dirname(parent).length + 1)); parent = dirname(parent); }
+  if (!localStat(parent).isDirectory() || localStat(parent).isSymbolicLink()) throw new Error('Raiz local exige diretorio real.');
+  const canonical = canonicalExisting(parent);
+  return { root: join(canonical, ...missing), parent: canonical };
+}
+
+// Os padrões vêm do hub; apenas os nomes concretos dos derivados são calculados.
+export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
+  const resolved = localRoot(root); root = resolved.root;
+  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');
+  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');
+  const policy = JSON.parse(readFileSync(checkedLocalPath(localStat(localPolicy) ? localPolicy : fileURLToPath(new URL('../../templates/clients/ADAPTERS.json', import.meta.url))), 'utf8'));
+  const roots = [...new Set(policy.adapters.flatMap(adapter => [adapter.root, ...(adapter.extraRoots || [])]))].filter(path => !['.github', '.vscode'].includes(path));
+  if (roots.some(path => typeof path !== 'string' || !/^\.[a-z0-9][a-z0-9-]*$/.test(path) || ['.git', '.pbai4devs', '.agent-tests'].includes(path))) throw new Error('Raiz de cliente invalida para exclusao.');
+  const paths = [...new Set([...outputs.map(checkedOutput), ...template.split(/\r?\n/).filter(line => line.startsWith('/')).map(line => checkedOutput(line.slice(1)))])].sort();
+  const info = gitCommand(resolved.parent, ['rev-parse', '--show-toplevel', '--git-path', 'info/exclude']);
+  let location = null;
+  if (info.status === 0) {
+    const [reportedTop, reportedExclude] = info.stdout.trimEnd().split(/\r?\n/);
+    if (!reportedTop || !reportedExclude) throw new Error('Localizacao Git invalida.');
+    const exclude = resolve(resolved.parent, reportedExclude);
+    const top = canonicalExisting(reportedTop);
+    const prefix = relative(top, root);
+    if (isAbsolute(prefix) || prefix === '..' || prefix.startsWith(`..${sep}`)) throw new Error('Projeto fora da arvore Git.');
+    checkedLocalPath(exclude);
+    const canonicalExclude = localStat(exclude) ? canonicalExisting(exclude) : join(localRoot(dirname(exclude)).root, basename(exclude));
+    location = { top, exclude: checkedLocalPath(canonicalExclude), prefix: portable(prefix) };
+  } else if (info.error && info.error.code !== 'ENOENT' || !info.error && !/not a git repository/i.test(info.stderr || '')) {
+    throw new Error(`Nao foi possivel localizar Git: ${info.error?.message || info.stderr}`);
+  }
+  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 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 probes = [...paths, ...rootProbes(root, roots)];
+  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;
+  }
+  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 });
+  }
+  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 };
+}
+
+export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
+  const missing = [];
+  const replacements = replacedBlocks.map(item => {
+    const path = canonicalExisting(checkedLocalPath(resolve(item.path))), inside = relative(localRoot(plan.root).root, path);
+    if (isAbsolute(inside) || inside === '..' || inside.startsWith(`..${sep}`) || !Number.isInteger(item.firstLine) || !Number.isInteger(item.lastLine) || item.firstLine < 1 || item.lastLine < item.firstLine || !/^[a-f0-9]{64}$/.test(item.sha256)) throw new Error('Faixa de ignore gerenciado invalida.');
+    const content = readFileSync(checkedLocalPath(path), 'utf8');
+    const lines = [...content.matchAll(/[^\r\n]*(?:\r\n|\n|\r|$)/g)].filter(match => match[0]);
+    if (item.lastLine > lines.length) throw new Error('Faixa de ignore fora do arquivo.');
+    const first = lines[item.firstLine - 1], last = lines[item.lastLine - 1];
+    const block = content.slice(first.index, last.index + last[0].replace(/[\r\n]+$/, '').length);
+    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] });
+    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 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]);
+    }
+  }
+  return { ok: plan.edits.length === 0 && missing.length === 0 && plan.trackedOutputs.length === 0, status: plan.status, missing, trackedOutputs: plan.trackedOutputs, changed: plan.edits.length };
+}
+
+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}`);
+  }
+}
+
+export function applyLocalIgnore(plan) {
+  assertLocalIgnoreUnchanged(plan);
+  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);
+    }
+    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);
+    }
+    throw error;
+  }
+  return { status: plan.status, changed: plan.edits.length, trackedOutputs: plan.trackedOutputs };
+}
+
+export function planUntrack(root, expectedHashes = {}) {
+  root = localRoot(root).root;
+  const candidates = Object.keys(expectedHashes).map(checkedOutput).sort();
+  for (const hash of Object.values(expectedHashes)) if (!/^[a-f0-9]{64}$/.test(hash)) throw new Error('Hash de ownership invalido para desindexar.');
+  if (!candidates.length || !localStat(root)) return { root, paths: [], hashes: {}, index: '', conflicts: [] };
+  const result = gitCommand(root, ['ls-files', '--stage', '-z']);
+  if (result.status !== 0) {
+    if (result.error?.code === 'ENOENT' || /not a git repository/i.test(result.stderr || '')) return { root, paths: [], hashes: {}, index: '', conflicts: [] };
+    throw new Error(result.error?.message || result.stderr || 'Falha ao ler indice Git.');
+  }
+  const conflicts = [];
+  const records = result.stdout.split('\0').filter(Boolean);
+  const wanted = new Set(candidates);
+  const matches = new Map();
+  for (const record of records) {
+    const position = record.indexOf('\t'), path = record.slice(position + 1);
+    if (position < 0 || !wanted.has(path)) continue;
+    matches.set(path, [...(matches.get(path) || []), record]);
+  }
+  const paths = [...matches.keys()].filter(path => {
+    const file = checkedLocalPath(join(root, path));
+    const entries = matches.get(path);
+    const match = entries.length === 1 && entries[0].match(/^\d+ ([a-f0-9]+) 0\t/);
+    const blob = match ? gitCommand(root, ['cat-file', 'blob', match[1]]) : null;
+    const owned = localStat(file) && createHash('sha256').update(readFileSync(file)).digest('hex') === expectedHashes[path];
+    const indexOwned = blob?.status === 0 && createHash('sha256').update(blob.stdout).digest('hex') === expectedHashes[path];
+    if (!owned || !indexOwned) conflicts.push(path);
+    return owned && indexOwned;
+  });
+  const selected = new Set(paths);
+  const index = records.filter(record => selected.has(record.slice(record.indexOf('\t') + 1))).join('\0');
+  return { root, paths, hashes: Object.fromEntries(paths.map(path => [path, expectedHashes[path]])), index, conflicts };
+}
+
+export function applyUntrack(plan) {
+  if (plan.conflicts?.length) throw new Error(`Indice contem alteracoes nao pertencentes ao kit: ${plan.conflicts.join(', ')}`);
+  if (!plan.paths.length) return { removed: [] };
+  const current = planUntrack(plan.root, plan.hashes);
+  if (current.index !== plan.index || current.paths.length !== plan.paths.length) throw new Error('Ownership ou indice mudou antes de desindexar.');
+  const location = gitCommand(plan.root, ['rev-parse', '--show-toplevel']);
+  if (location.status !== 0 || location.error) throw new Error('Nao foi possivel localizar a raiz Git para desindexar.');
+  const top = canonicalExisting(location.stdout.trimEnd()), prefix = portable(relative(top, localRoot(plan.root).root));
+  const paths = plan.paths.map(path => prefix ? `${prefix}/${path}` : path);
+  const result = gitCommand(top, ['rm', '--cached', '--pathspec-from-file=-', '--pathspec-file-nul'], paths.join('\0') + '\0');
+  if (result.status !== 0 || result.error) throw new Error(result.error?.message || result.stderr || 'Falha ao desindexar derivados.');
+  return { removed: [...plan.paths] };
+}
+
+// Reconstitui apenas entradas removidas; o índice atual e alterações concorrentes
+// permanecem. O lock é do próprio Git e o trabalho ocorre numa cópia desse índice.
+export function restoreUntrack(plan) {
+  if (!plan?.paths?.length) return { restored: [], preserved: [] };
+  const located = gitCommand(plan.root, ['rev-parse', '--show-toplevel', '--git-path', 'index']);
+  if (located.status !== 0 || located.error) throw new Error('Nao foi possivel localizar o indice para rollback.');
+  const [reportedTop, relativeIndex] = located.stdout.trimEnd().split(/\r?\n/);
+  const reportedIndex = resolve(plan.root, relativeIndex);
+  checkedLocalPath(reportedIndex);
+  const top = canonicalExisting(reportedTop), indexPath = canonicalExisting(reportedIndex);
+  checkedLocalPath(indexPath);
+  if (!localStat(indexPath)) throw new Error('Indice ausente; rollback automatico recusado.');
+  const lock = `${indexPath}.lock`;
+  let descriptor, acquired = false;
+  try {
+    descriptor = openSync(lock, 'wx');
+    acquired = true;
+    writeFileSync(descriptor, readFileSync(indexPath));
+    const current = gitCommand(plan.root, ['ls-files', '--stage', '-z']);
+    if (current.status !== 0 || current.error) throw new Error('Nao foi possivel ler indice atual para rollback.');
+    const existing = new Set(current.stdout.split('\0').filter(Boolean).map(record => record.slice(record.indexOf('\t') + 1)));
+    const entries = plan.index.split('\0').filter(Boolean);
+    const selected = new Set(plan.paths), restored = [], preserved = [];
+    const prefix = portable(relative(top, localRoot(plan.root).root));
+    const records = [];
+    for (const record of entries) {
+      const at = record.indexOf('\t'), path = record.slice(at + 1);
+      if (!selected.has(path)) continue;
+      if (existing.has(path)) { preserved.push(path); continue; }
+      restored.push(path);
+      records.push(record.slice(0, at + 1) + (prefix ? `${prefix}/${path}` : path));
+    }
+    if (!records.length) return { restored, preserved };
+    const env = { ...process.env };
+    for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete env[key];
+    env.GIT_INDEX_FILE = lock;
+    const result = spawnSync('git', ['-C', top, 'update-index', '-z', '--index-info'], { input: records.join('\0') + '\0', encoding: 'utf8', env, windowsHide: true, timeout: 20000 });
+    if (result.status !== 0 || result.error) throw new Error(result.error?.message || result.stderr || 'Rollback do indice falhou.');
+    closeSync(descriptor); descriptor = undefined;
+    renameSync(lock, indexPath);
+    return { restored, preserved };
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+    if (acquired) rmSync(lock, { force: true });
+  }
+}
+
+export function mergeGitignore(current, template) {
+  if (typeof current !== 'string' || typeof template !== 'string' || current.includes('\0') || template.includes('\0')) throw new Error('Conteudo .gitignore invalido.');
+  const body = template.replace(/\r\n?/g, '\n').replace(/\n*$/, '');
+  if (!body.trim() || body.split('\n').some(line => [ignoreBegin, ignoreEnd].includes(line.trim()))) throw new Error('Template .gitignore vazio ou com marcadores reservados.');
+  const markers = [];
+  const lines = /([^\r\n]*)(\r\n|\n|\r|$)/g;
+  for (const match of current.matchAll(lines)) {
+    const value = match[1].trim();
+    if ([ignoreBegin, ignoreEnd].includes(value)) markers.push({ value, start: match.index, end: match.index + match[0].length });
+  }
+  const block = `${ignoreBegin}\n${body}\n${ignoreEnd}\n`;
+  if (!markers.length) {
+    const separator = !current || /(?:\r\n|\n|\r){2}$/.test(current) ? '' : /(?:\r\n|\n|\r)$/.test(current) ? '\n' : '\n\n';
+    return { text: current + separator + block, hasBlock: false };
+  }
+  if (markers.length !== 2 || markers[0].value !== ignoreBegin || markers[1].value !== ignoreEnd) throw new Error('Marcadores .gitignore incompletos, duplicados ou fora de ordem.');
+  return { text: current.slice(0, markers[0].start) + block + current.slice(markers[1].end), hasBlock: true };
+}

package/.pbai4devs/scripts/lib/npm.mjs

@@ -0,0 +1,17 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+
+export function npmCandidates({ node = process.execPath, environment = process.env } = {}) {
+  const candidates = [join(dirname(node), 'node_modules/npm/bin/npm-cli.js'), join(dirname(node), '../lib/node_modules/npm/bin/npm-cli.js'), environment.npm_execpath];
+  for (const entry of (environment.PATH || environment.Path || '').split(delimiter).filter(Boolean)) {
+    for (const name of ['npm', 'npm.cmd']) {
+      const file = join(entry, name);
+      if (existsSync(file)) candidates.push(realpathSync(file), join(entry, 'node_modules/npm/bin/npm-cli.js'));
+    }
+  }
+  return [...new Set(candidates.filter(file => file && file.endsWith('npm-cli.js') && existsSync(file) && statSync(file).isFile()).map(file => realpathSync(file)))];
+}
+
+export function findNpmCli(options) {
+  return npmCandidates(options)[0] || null;
+}

package/.pbai4devs/scripts/lib/resource-path.mjs

@@ -0,0 +1,20 @@
+import { posix } from 'node:path';
+const principals = { skills: 'SKILL.md', agents: 'AGENT.md', commands: 'COMMAND.md', rules: 'RULE.md' };
+const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'instrucoes', 'prompt', 'agente']);
+const fail = message => { throw new Error(message); };
+// Layouts de arquivo preservam os grupos, retirando apenas o nome do principal.
+export function resourcePath(source, kind, mode = 'agrupado') {
+  if (!Object.hasOwn(principals, kind) || !layouts.has(mode)) fail(`Formato invalido: ${kind}/${mode}`);
+  const path = source.slice('.pbai4devs/'.length);
+  if (mode === 'agrupado') return path;
+  const slug = posix.basename(posix.dirname(source));
+  if (mode === 'plano') {
+    if (!/^[a-z0-9-]+$/.test(slug)) fail(`Nome invalido para layout plano: ${source}`);
+    return kind === 'skills' ? `skills/${slug}/SKILL.md` : `${kind}/${slug}.md`;
+  }
+  if (kind === 'skills') fail(`Skills exigem formato agrupado ou plano: ${mode}`);
+  const folder = posix.dirname(path);
+  const extensions = { arquivo: '.md', mdc: '.mdc', instrucoes: '.instructions.md', prompt: '.prompt.md', agente: '.agent.md' };
+  const scopes = { instrucoes: 'instructions', prompt: 'prompts' };
+  return `${scopes[mode] || kind}${folder.slice(kind.length)}${extensions[mode]}`;
+}

package/.pbai4devs/scripts/lib/runtime.mjs

@@ -0,0 +1,28 @@
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { accessSync, constants, statSync } from 'node:fs';
+
+export const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+
+export function requireNode(minimum = 24, version = process.versions.node) {
+  if (process.versions.bun || !/^\d+\.\d+\.\d+/.test(version || '') || Number(version.split('.')[0]) < minimum) {
+    throw new Error(`Instale Node.js >=${minimum} com npm: https://nodejs.org/en/download .`);
+  }
+}
+
+export function isMain(metaUrl) {
+  return Boolean(process.argv[1]) && metaUrl === pathToFileURL(resolve(process.argv[1])).href;
+}
+
+export function findExecutable(name, environment = process.env, platform = process.platform) {
+  const extensions = platform === 'win32' ? (environment.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : [''];
+  const names = platform === 'win32' && !/\.[^/\\]+$/.test(name) ? [name, ...extensions.map(ext => name + ext.toLowerCase())] : [name];
+  const directories = isAbsolute(name) ? [''] : (environment.PATH || environment.Path || '').split(delimiter).filter(Boolean);
+  for (const directory of directories) for (const candidate of names) {
+    const file = directory ? join(directory, candidate) : candidate;
+    try {
+      if (statSync(file).isFile()) { accessSync(file, platform === 'win32' ? constants.F_OK : constants.X_OK); return resolve(file); }
+    } catch { /* Candidato ausente ou sem permissao. */ }
+  }
+  return null;
+}

package/.pbai4devs/scripts/lib/script-config.mjs

@@ -0,0 +1,8 @@
+// Contrato unico do seletor e do catalogo para SCRIPT.conf.
+export function parseScriptConfig(text) {
+  const entries = text.split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#'));
+  if (entries.length !== 1 || !/^executor\s*=\s*(node|playwright-mcp)$/.test(entries[0])) {
+    throw new Error('SCRIPT.conf exige uma unica entrada executor=node ou executor=playwright-mcp.');
+  }
+  return entries[0].split('=')[1].trim();
+}

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

@@ -0,0 +1,34 @@
+---
+description: Recuperação de Node.js por JavaScript sem instalação global.
+---
+
+# Preparar o runtime
+
+O inicializador usa Node.js 18+ para preparar Node.js 24+ e npm locais.
+Se Node/npm estiverem totalmente ausentes, o agente deve instalá-los pelo
+gerenciador do sistema operacional antes de executar JavaScript ou npx.
+
+Com Node disponível, execute na raiz do projeto:
+
+```text
+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.
+
+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.
+Windows usa ZIP; macOS/Linux usam tar.gz. Não há scripts Bash ou PowerShell,
+mudança permanente de PATH ou instalação global neste fluxo.
+
+O cache fica em `.pbai4devs/tools/.cache/runtime/`. Falhas de download,
+integridade ou validação preservam o runtime anterior. Arquivos e links fora
+da distribuição são recusados. `tar` deve estar disponível no sistema.
+
+Navegadores, permissões desktop e FFmpeg dependem da tarefa e não são
+instalados ou ativados por este inicializador.
+
+Fonte: [distribuições oficiais do Node.js][node].
+
+[node]: https://nodejs.org/dist/latest-v24.x/