@pathbit/agentdevkit 0.0.11 → 0.0.12

package/.pbai4devs/rules/documentacao/RULE.md

@@ -8,6 +8,8 @@ description: Documentação e revisão fazem parte de toda entrega implementada.
 Antes de criar, organizar ou alterar documentação, use `atualizar-documentacao`:
 inventarie e leia o que já existe. Reutilize caminhos e formatos;
 complemente lacunas sem apagar, mover ou substituir arquivos por templates.
+Em instruções existentes dos agentes, acrescente somente a referência do kit;
+preserve texto, nomes e metadados humanos, inclusive em colisões de nomes.
 
 Após implementar, siga `atualizar-documentacao` e o comando `revisar-entrega`
 antes de commit ou merge. Use os modelos da fase atual; registre decisões sem

package/.pbai4devs/scripts/lib/README.md

@@ -7,3 +7,7 @@ description: Utilitários mínimos compartilhados das automações Node.js.
 `runtime.mjs` centraliza o requisito Node.js 24+, a raiz do repositório e a
 identificação do arquivo executado. Não instala runtimes nem configura a máquina.
 Também procura executáveis opcionais no PATH sem iniciar um shell.
+
+`managed-content.mjs` limita a propriedade do kit aos seus blocos Markdown;
+`managed-toml.mjs` aplica o mesmo contrato ao `prompt` de comandos Gemini.
+Texto externo, nomes existentes e metadados humanos permanecem preservados.

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

@@ -125,6 +125,34 @@ function artifactPolicy(templateFile) {
   return patterns;
 }
 
+function privateClientPolicy(templateFile, roots) {
+  const adjacent = join(dirname(templateFile), 'agents.ignore');
+  const source = checkedLocalPath(localStat(adjacent) ? adjacent : fileURLToPath(new URL('../../templates/gitignore/agents.ignore', import.meta.url)));
+  const section = readFileSync(source, 'utf8').split(/^## Estado local, caches e credenciais conhecidas\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 => !/^(?:!?\*\*\/|\/)/.test(pattern) || /[\\\x00-\x1f]/.test(pattern) || pattern.split('/').includes('..'))) throw new Error('Secao de estado local invalida em agents.ignore.');
+  const rules = [], probes = [];
+  for (const root of roots) for (const pattern of patterns) {
+    const negative = pattern.startsWith('!'), rule = pattern.replace(/^!/, '').replace(/^\//, '');
+    rules.push(`${negative ? '!' : ''}/${escapePattern(root)}/${rule}`);
+    if (negative) continue;
+    const stem = rule.replace(/^\*\*\//, '').replace(/\[([^\]]+)\]/g, (_match, letters) => letters[0]).replace(/\*/g, 'agentdevkit-private-probe').replace(/\?/g, 'x');
+    probes.push(`${root}/${stem}${stem.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+    if (rule.startsWith('**/')) probes.push(`${root}/.agentdevkit-ignore-probes/${stem}${stem.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+  }
+  return { rules, probes };
+}
+
+function safeIgnoreProbe(root, path) {
+  let parent = root;
+  for (const part of path.split('/').slice(0, -1)) {
+    parent = join(parent, part);
+    const item = localStat(parent);
+    if (item && !item.isDirectory()) return false;
+  }
+  return true;
+}
+
 function artifactProbes(root, patterns) {
   const probes = new Set();
   for (const pattern of patterns) {
@@ -233,10 +261,14 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   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}}.');
+  // A client directory can also contain human instructions and settings. Only
+  // whole files owned by the kit belong in the local output exclusion list.
+  const 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 clientRoots = [...new Set(policy.adapters.flatMap(adapter => [adapter.root, ...(adapter.extraRoots || [])]))];
+  if (clientRoots.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 privateClients = privateClientPolicy(templateFile, clientRoots);
   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;
@@ -256,13 +288,18 @@ 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'))
+    + '\n# Estado privado dos clientes\n' + privateClients.rules.join('\n') + '\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 body = fixed.split(/\r?\n/).map(line => {
+    if (!location?.prefix) return line;
+    if (line.startsWith('!/')) return `!/${escapePattern(location.prefix)}${line.slice(1)}`;
+    return 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, beforeMode: localMode(target) }];
   const probes = [...paths, ...rootProbes(root, roots)];
-  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
+  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...privateClients.probes.filter(path => safeIgnoreProbe(root, path)), ...(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 = ignoreMatches(location, [...probes, ...artifactPaths]);

package/.pbai4devs/scripts/lib/managed-content.mjs

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { readdirSync } from 'node:fs';
+
+export const managedBegin = '<!-- BEGIN AGENTDEVKIT -->';
+export const managedEnd = '<!-- END AGENTDEVKIT -->';
+const digest = value => createHash('sha256').update(value).digest('hex');
+const fail = message => { throw Object.assign(new Error(message), { code: 'E_MANAGED_BLOCK' }); };
+
+export function canonicalEntrypoint(path) {
+  return ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].find(name => name.toLowerCase() === path.toLowerCase()) || null;
+}
+
+export function resolveEntrypoint(root, canonical) {
+  if (!canonicalEntrypoint(canonical)) fail(`Entrada desconhecida: ${canonical}`);
+  let names;
+  try { names = readdirSync(root); }
+  catch (error) { if (error.code === 'ENOENT') return canonical; throw error; }
+  const matches = names.filter(name => name.toLowerCase() === canonical.toLowerCase());
+  if (matches.length > 1) fail(`Entradas ambiguas: ${matches.sort().join(', ')}`);
+  return matches[0] || canonical;
+}
+
+export function entrypointReference(root, path) {
+  const canonical = canonicalEntrypoint(path);
+  if (canonical === 'AGENTS.md') return 'Leia e siga [.pbai4devs/INSTRUCTIONS.md](.pbai4devs/INSTRUCTIONS.md).';
+  if (canonical === 'CLAUDE.md') return `@${resolveEntrypoint(root, 'AGENTS.md')}`;
+  if (canonical === 'GEMINI.md') return `@./${resolveEntrypoint(root, 'AGENTS.md')}`;
+  fail(`Entrada desconhecida: ${path}`);
+}
+
+export function renderEntrypointImports(root, text) {
+  const name = resolveEntrypoint(root, 'AGENTS.md');
+  return text.replace(/^(@(?:\.\/)?)AGENTS\.md(?=\r?$)/gim, (_match, prefix) => `${prefix}${name}`);
+}
+
+export function managedText(value) {
+  const text = Buffer.isBuffer(value) ? new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(value) : String(value ?? '');
+  if (text.includes('\0')) fail('Conteudo binario nao pode receber instrucoes Markdown.');
+  return text;
+}
+
+function locate(value) {
+  const text = managedText(value);
+  let fence = null, start = null, finish = null, offset = 0;
+  for (const match of text.matchAll(/([^\r\n]*)(\r\n|\r|\n|$)/g)) {
+    if (!match[0]) continue;
+    const line = match[1];
+    const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !marker[2].trim()) fence = null;
+    } else if (marker) fence = marker[1];
+    else if (line === managedBegin) {
+      if (start !== null || finish !== null) fail('Marcadores AgentDevKit duplicados.');
+      start = offset;
+    } else if (line === managedEnd) {
+      if (start === null || finish !== null) fail('Marcadores AgentDevKit incompletos.');
+      finish = offset + line.length;
+    }
+    offset += match[0].length;
+  }
+  if ((start === null) !== (finish === null)) fail('Marcadores AgentDevKit incompletos.');
+  return { text, start, finish, fence, block: start === null ? null : text.slice(start, finish) };
+}
+
+export function extractManagedBlock(value) { return locate(value).block; }
+export function managedBlockDigest(value) { const block = extractManagedBlock(value); return block === null ? null : digest(block); }
+
+export function mergeManagedContent(value, body, { expectedHash } = {}) {
+  const current = locate(value), eol = current.text.match(/\r\n|\n|\r/)?.[0] || '\n';
+  const content = managedText(body).trim().replace(/\r\n|\r|\n/g, eol);
+  if (!content || content.includes(managedBegin) || content.includes(managedEnd)) fail('Referencia AgentDevKit invalida.');
+  const block = `${managedBegin}${eol}${content}${eol}${managedEnd}`;
+  if (current.block !== null && (expectedHash ? digest(current.block) !== expectedHash : current.block !== block)) fail('Bloco AgentDevKit alterado; conteudo preservado.');
+  if (current.fence && current.block === null) fail('Bloco de codigo Markdown nao fechado; conteudo preservado.');
+  const separator = !current.text || current.text.endsWith(eol + eol) ? '' : /[\r\n]$/.test(current.text) ? eol : eol + eol;
+  const text = current.block === null ? `${current.text}${separator}${block}${eol}`
+    : current.text.slice(0, current.start) + block + current.text.slice(current.finish);
+  return { text, block, sha256: digest(block), changed: text !== current.text };
+}
+
+export function stripManagedContent(value, expectedHash) {
+  const current = locate(value);
+  if (current.block === null) return current.text;
+  if (!expectedHash || digest(current.block) !== expectedHash) fail('Bloco AgentDevKit alterado; conteudo preservado.');
+  return current.text.slice(0, current.start) + current.text.slice(current.finish);
+}

package/.pbai4devs/scripts/lib/managed-toml.mjs

@@ -0,0 +1,192 @@
+import { extractManagedBlock, managedBlockDigest, managedText, mergeManagedContent, stripManagedContent } from './managed-content.mjs';
+
+// Localized editing of Gemini's root prompt; not a general TOML serializer.
+const fail = message => { throw Object.assign(new Error(message), { code: 'E_MANAGED_BLOCK' }); };
+const horizontal = character => character === ' ' || character === '\t';
+const whitespace = character => horizontal(character) || character === '\n' || character === '\r';
+const escapes = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+
+function scalar(code) {
+  if (code > 0x10ffff || code >= 0xd800 && code <= 0xdfff) fail('Escape Unicode TOML invalido.');
+  return String.fromCodePoint(code);
+}
+
+function stringAt(text, start, key = false) {
+  const quote = text[start];
+  if (!['"', "'"].includes(quote)) fail('O prompt TOML deve ser uma string.');
+  const multiline = text.slice(start, start + 3) === quote.repeat(3);
+  if (key && multiline) fail('Chave TOML multiline nao suportada.');
+  const basic = quote === '"';
+  let position = start + (multiline ? 3 : 1), value = '';
+  if (multiline) {
+    if (text.slice(position, position + 2) === '\r\n') position += 2;
+    else if (text[position] === '\n') position++;
+  }
+  while (position < text.length) {
+    const character = text[position];
+    if (character === quote) {
+      if (!multiline) return { start, end: position + 1, value };
+      let count = 1;
+      while (text[position + count] === quote) count++;
+      if (count >= 3) {
+        if (count > 5) fail('Delimitador TOML ambiguo.');
+        return { start, end: position + count, value: value + quote.repeat(count - 3) };
+      }
+      value += quote.repeat(count); position += count; continue;
+    }
+    if (basic && character === '\\') {
+      const escaped = text[++position];
+      if (multiline && whitespace(escaped)) {
+        let cursor = position, lineBreak = false;
+        while (whitespace(text[cursor])) {
+          if (text[cursor] === '\r') {
+            if (text[cursor + 1] !== '\n') fail('TOML exige LF ou CRLF.');
+            lineBreak = true; cursor += 2;
+          } else { if (text[cursor] === '\n') lineBreak = true; cursor++; }
+        }
+        if (!lineBreak) fail('Continuacao de string TOML invalida.');
+        position = cursor; continue;
+      }
+      if (Object.hasOwn(escapes, escaped)) { value += escapes[escaped]; position++; continue; }
+      if (escaped === 'u' || escaped === 'U') {
+        const width = escaped === 'u' ? 4 : 8, digits = text.slice(position + 1, position + 1 + width);
+        if (!new RegExp(`^[0-9a-fA-F]{${width}}$`).test(digits)) fail('Escape Unicode TOML invalido.');
+        value += scalar(Number.parseInt(digits, 16)); position += width + 1; continue;
+      }
+      fail('Escape TOML nao suportado.');
+    }
+    const code = text.charCodeAt(position);
+    if (code === 0x7f || code < 0x20 && character !== '\t' && !(multiline && ['\r', '\n'].includes(character))) fail('Controle invalido em string TOML.');
+    if (!multiline && ['\r', '\n'].includes(character)) fail('String TOML de uma linha interrompida.');
+    if (character === '\r' && text[position + 1] !== '\n') fail('TOML exige LF ou CRLF.');
+    value += character; position++;
+  }
+  fail('String TOML sem fechamento.');
+}
+
+function keyAt(text, start) {
+  let position = start;
+  const path = [];
+  while (true) {
+    while (horizontal(text[position])) position++;
+    if (['"', "'"].includes(text[position])) {
+      const part = stringAt(text, position, true); path.push(part.value); position = part.end;
+    } else {
+      const part = /^[A-Za-z0-9_-]+/.exec(text.slice(position));
+      if (!part) fail('Chave TOML nao suportada.');
+      path.push(part[0]); position += part[0].length;
+    }
+    while (horizontal(text[position])) position++;
+    if (text[position] !== '.') break;
+    position++;
+  }
+  return { path, end: position };
+}
+
+function valueEnd(text, start) {
+  if (['"', "'"].includes(text[start])) return stringAt(text, start).end;
+  const stack = [];
+  let position = start;
+  while (position < text.length) {
+    const character = text[position];
+    if (['"', "'"].includes(character)) { position = stringAt(text, position).end; continue; }
+    if (character === '#') {
+      if (!stack.length) break;
+      while (position < text.length && !['\r', '\n'].includes(text[position])) position++;
+      continue;
+    }
+    if (['\n', '\r'].includes(character) && !stack.length) break;
+    if (character === '[' || character === '{') stack.push(character);
+    if (character === ']' || character === '}') {
+      if (stack.pop() !== (character === ']' ? '[' : '{')) fail('Valor TOML desbalanceado.');
+    }
+    position++;
+  }
+  if (stack.length || !text.slice(start, position).trim()) fail('Valor TOML incompleto.');
+  return position;
+}
+
+function statementEnd(text, start) {
+  let position = start;
+  while (horizontal(text[position])) position++;
+  if (text[position] === '#') while (position < text.length && !['\r', '\n'].includes(text[position])) position++;
+  if (position < text.length && !['\r', '\n'].includes(text[position])) fail('Texto inesperado apos valor TOML.');
+  if (text[position] === '\r') {
+    if (text[position + 1] !== '\n') fail('TOML exige LF ou CRLF.');
+    return position + 2;
+  }
+  return text[position] === '\n' ? position + 1 : position;
+}
+
+function locatePrompt(input) {
+  let text;
+  try { text = managedText(input); }
+  catch (error) {
+    if (error.code === 'E_MANAGED_BLOCK') throw error;
+    fail('Texto TOML deve ser UTF-8 valido.');
+  }
+  for (const character of text) {
+    const code = character.codePointAt(0);
+    if (code >= 0xd800 && code <= 0xdfff) fail('Unicode TOML invalido.');
+  }
+  let position = text.startsWith('\ufeff') ? 1 : 0, root = true, insertion = text.length, prompt = null, reserved = false;
+  while (position < text.length) {
+    const lineStart = position;
+    while (horizontal(text[position])) position++;
+    if (position === text.length) break;
+    if (text[position] === '#' || ['\r', '\n'].includes(text[position])) { position = statementEnd(text, position); continue; }
+    if (text[position] === '[') {
+      const arrayTable = text[position + 1] === '[';
+      const header = keyAt(text, position + (arrayTable ? 2 : 1));
+      if (text.slice(header.end, header.end + (arrayTable ? 2 : 1)) !== (arrayTable ? ']]' : ']')) fail('Tabela TOML invalida.');
+      if (root) insertion = lineStart;
+      root = false;
+      if (header.path[0] === 'prompt') reserved = true;
+      position = statementEnd(text, header.end + (arrayTable ? 2 : 1)); continue;
+    }
+    const key = keyAt(text, position);
+    if (text[key.end] !== '=') fail('Atribuicao TOML invalida.');
+    position = key.end + 1;
+    while (horizontal(text[position])) position++;
+    if (root && key.path[0] === 'prompt') {
+      if (key.path.length !== 1 || prompt || reserved) fail('Prompt TOML duplicado ou ambiguo.');
+      prompt = stringAt(text, position);
+      position = prompt.end;
+    } else position = valueEnd(text, position);
+    position = statementEnd(text, position);
+  }
+  if (reserved) fail('Prompt TOML ocupa uma tabela; conteudo preservado.');
+  return { text, prompt, insertion };
+}
+
+function encode(value) {
+  return JSON.stringify(value).replace(/\x7f/g, '\\u007F');
+}
+
+export function extractTomlManagedBlock(input) {
+  const { prompt } = locatePrompt(input);
+  return prompt ? extractManagedBlock(prompt.value) : null;
+}
+
+export function tomlManagedBlockDigest(input) {
+  const { prompt } = locatePrompt(input);
+  return prompt ? managedBlockDigest(prompt.value) : null;
+}
+
+export function mergeTomlContent(input, body, options = {}) {
+  const { text, prompt, insertion } = locatePrompt(input);
+  const result = mergeManagedContent(prompt?.value ?? '', body, options);
+  if (prompt && !result.changed) return { ...result, text, changed: false };
+  const eol = text.match(/\r\n|\n/)?.[0] || '\n';
+  const separator = insertion && !/[\r\n]$/.test(text.slice(0, insertion)) ? eol : '';
+  const content = prompt ? text.slice(0, prompt.start) + encode(result.text) + text.slice(prompt.end)
+    : text.slice(0, insertion) + separator + `prompt = ${encode(result.text)}${eol}` + text.slice(insertion);
+  return { ...result, text: content, changed: content !== text };
+}
+
+export function stripTomlContent(input, expectedHash) {
+  const { text, prompt } = locatePrompt(input);
+  if (!prompt) return text;
+  const stripped = stripManagedContent(prompt.value, expectedHash);
+  return stripped === prompt.value ? text : text.slice(0, prompt.start) + encode(stripped) + text.slice(prompt.end);
+}

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

@@ -12,9 +12,11 @@ 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.
+Recursos nativos humanos recebem um bloco curto com a referência ao hub.
+Texto, frontmatter e nomes existentes são preservados. O estado guarda só o
+hash desse bloco; edições externas continuam permitidas. Um bloco alterado
+não é sobrescrito por `--force`. Links humanos continuam opacos.
+Comandos Gemini recebem o complemento dentro do `prompt` TOML.
 
 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
@@ -36,9 +38,9 @@ a seleção, use `agentdevkit agents <lista>`; não edite o manifesto gerado.
 Os derivados ficam locais: catálogos, manifesto, estado e apontamentos são
 excluídos pelo Git. O bloco em `.git/info/exclude` preserva regras próprias;
 sem Git, usa um bloco na raiz que migra ao executar depois de `git init`.
-Raízes dedicadas são locais por completo; `.github` e `.vscode` excluem somente
-os arquivos gerados. Conteúdo próprio permanece no disco e não é desindexado
-sem comprovação de propriedade do kit.
+Somente arquivos integralmente gerados são excluídos; pastas de clientes podem
+conter arquivos humanos versionados. Conteúdo próprio não é desindexado pela
+presença de um bloco gerenciado.
 Entradas novas usam os templates; hashes em `estado/derived.json` permitem
-atualizar apenas arquivos integralmente gerados, preservando alterações humanas.
+atualizar arquivos gerados e blocos separadamente, preservando alterações humanas.
 `--check` também acusa derivados ainda rastreados; não altera o índice.