@pathbit/agentdevkit 0.0.12 → 0.0.13

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

@@ -11,3 +11,7 @@ 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.
+
+`gitignore.mjs` planeja exclusões locais e detecta regras conflitantes. Com
+exceções na raiz, pode acrescentar um bloco limitado ao estado privado dos
+clientes; alterações no bloco gerenciado impedem sua substituição.

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

@@ -136,9 +136,11 @@ function privateClientPolicy(templateFile, roots) {
     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' : ''}`);
+    const witness = lower => rule.replace(/^\*\*\//, '').replace(/\[([^\]]+)\]/g, (_match, letters) => lower ? letters[0].toLowerCase() : letters[0]).replace(/\*/g, 'agentdevkit-private-probe').replace(/\?/g, 'x');
+    for (const variant of new Set([witness(false), witness(true)])) {
+      probes.push(`${root}/${variant}${variant.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+      if (rule.startsWith('**/')) probes.push(`${root}/.agentdevkit-ignore-probes/${variant}${variant.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+    }
   }
   return { rules, probes };
 }
@@ -300,6 +302,17 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const edits = before === after ? [] : [{ path: target, before, after, beforeMode: localMode(target) }];
   const probes = [...paths, ...rootProbes(root, roots)];
   const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...privateClients.probes.filter(path => safeIgnoreProbe(root, path)), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
+  const privateProbes = privateClients.probes.filter(path => safeIgnoreProbe(root, path));
+  const rootOverrideProbes = new Set();
+  const overrideFirst = `# BEGIN AGENTDEVKIT PRIVATE ${id}`, overrideLast = `# END AGENTDEVKIT PRIVATE ${id}`;
+  if (location) {
+    const humanIgnore = localRead(checkedLocalPath(join(root, '.gitignore')));
+    const withoutFallback = localBlock(humanIgnore, first, last, null);
+    const withoutOwned = localBlock(withoutFallback, overrideFirst, overrideLast, null);
+    // Any root negation can match an arbitrary spelling or wildcard value.
+    // Protect private client paths deterministically instead of sampling it.
+    if (withoutOwned.replace(/^\uFEFF/, '').split(/\r?\n/).some(line => line.startsWith('!'))) for (const path of privateProbes) rootOverrideProbes.add(path);
+  }
   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]);
@@ -307,11 +320,19 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   }
   if (location) {
     const fallback = checkedLocalPath(join(root, '.gitignore'));
-    const old = localRead(fallback), next = localBlock(old, first, last, null);
+    const old = localRead(fallback);
+    let next = localBlock(old, first, last, null);
+    if (rootOverrideProbes.size || old?.includes(overrideFirst) || old?.includes(overrideLast)) {
+      const overrideBody = privateClients.rules.join('\n');
+      if ((old?.includes(overrideFirst) || old?.includes(overrideLast)) && localBlock(old, overrideFirst, overrideLast, overrideBody) !== old) throw new Error('Bloco privado AgentDevKit alterado; conteudo preservado.');
+      const end = next.indexOf(overrideLast);
+      if (end >= 0 && next.slice(end + overrideLast.length).split(/\r?\n/).some(line => line.startsWith('!'))) next = localBlock(next, overrideFirst, overrideLast, null);
+      next = localBlock(next, overrideFirst, overrideLast, overrideBody);
+    }
     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, artifactPatterns: artifacts, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
+  return { root, status: location ? 'git' : 'fallback', location, paths, roots, artifactPatterns: artifacts, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last, rootOverrideProbes: [...rootOverrideProbes] };
 }
 
 export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
@@ -337,7 +358,8 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
       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 || !local)) || humanOverride)) missing.push(probes[index]);
+      const pendingRootOverride = humanOverride && plan.rootOverrideProbes?.includes(probes[index]) && plan.edits.some(edit => edit.path === join(plan.root, '.gitignore'));
+      if (!replaced && !pendingRootOverride && ((!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 };

package/.pbai4devs/scripts/sincronizar-agentes/tests/LOCAL_IGNORE.mjs

@@ -68,6 +68,92 @@ test('check identifica negação humana e outputs rastreados sem alterar o índi
   assert.equal(git(root, ['ls-files', 'generated.md']).trim(), 'generated.md');
 });
 
+test('negação genérica de cache preserva regras humanas e protege caches de clientes', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  git(root, ['config', 'core.ignorecase', 'false']);
+  const original = '# Regras do projeto\n!*.[Cc]ache/\n';
+  put(root, '.gitignore', original); git(root, ['add', '.gitignore']);
+  const index = git(root, ['ls-files', '--stage', '-z']);
+  const plan = planLocalIgnore(root);
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), original);
+  assert.equal(existsSync(join(root, '.cursor')), false);
+  applyLocalIgnore(plan);
+  const updated = readFileSync(join(root, '.gitignore'), 'utf8');
+  assert.ok(updated.startsWith(original));
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+  assert.equal(existsSync(join(root, '.cursor')), false);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+  put(root, '.cursor/.CACHE/private.json', 'local');
+  put(root, '.cursor/.cache/private.json', 'local');
+  put(root, '.cursor/human.md', 'human');
+  assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.CACHE/private.json']).includes('.cursor/.CACHE/private.json'));
+  assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.cache/private.json']).includes('.cursor/.cache/private.json'));
+  const visible = spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', '.cursor/human.md']);
+  assert.equal(visible.status, 1);
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), updated);
+  put(root, '.gitignore', updated + '# edição humana posterior\n');
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+});
+
+test('bloco privado modificado é preservado e recusa atualização', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!*.[Cc]ache/\n');
+  applyLocalIgnore(planLocalIgnore(root));
+  const path = join(root, '.gitignore');
+  const changed = readFileSync(path, 'utf8').replace('# Estado local', '# Estado alterado');
+  // Alter a concrete managed rule, even if the template has no heading here.
+  const edited = changed.replace('/.cursor/', '/.cursor-alterado/');
+  assert.notEqual(edited, readFileSync(path, 'utf8'));
+  writeFileSync(path, edited);
+  assert.throws(() => planLocalIgnore(root), /Bloco privado AgentDevKit alterado/);
+  assert.equal(readFileSync(path, 'utf8'), edited);
+});
+
+test('negação com caixa mista não expõe cache em Git sensível a maiúsculas', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  git(root, ['config', 'core.ignorecase', 'false']);
+  put(root, '.gitignore', '!*.CaChE/\n');
+  put(root, '.cursor/.CaChE/private.json', 'local');
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+  assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.CaChE/private.json']).includes('.cursor/.CaChE/private.json'));
+});
+
+test('negações literais e com caixa mista não expõem estado privado', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  git(root, ['config', 'core.ignorecase', 'false']);
+  put(root, '.gitignore', '!*.LoCaL/\n!/.cursor/.env.production\n');
+  for (const path of ['.cursor/.LoCaL/private.json', '.cursor/.env.production']) put(root, path, 'privado');
+  applyLocalIgnore(planLocalIgnore(root));
+  for (const path of ['.cursor/.LoCaL/private.json', '.cursor/.env.production']) assert.ok(git(root, ['check-ignore', '--no-index', path]).includes(path));
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+});
+
+test('negação na primeira linha com BOM preserva bytes e protege segredos', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const original = '\uFEFF!/.cursor/.env.production\r\n';
+  put(root, '.gitignore', original); put(root, '.cursor/.env.production', 'privado');
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.ok(readFileSync(join(root, '.gitignore'), 'utf8').startsWith(original));
+  assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.env.production']).includes('.cursor/.env.production'));
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+});
+
+test('negação humana acrescentada após o bloco recebe proteção na próxima sincronização', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!*.cache/\n'); applyLocalIgnore(planLocalIgnore(root));
+  const path = join(root, '.gitignore');
+  writeFileSync(path, readFileSync(path, 'utf8') + '!/.cursor/.env.production\n');
+  put(root, '.cursor/.env.production', 'privado');
+  const plan = planLocalIgnore(root);
+  assert.ok(plan.edits.some(edit => edit.path === path));
+  applyLocalIgnore(plan);
+  assert.match(readFileSync(path, 'utf8'), /!\*\.cache\/\n!\/\.cursor\/\.env\.production\n/);
+  assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.env.production']).includes('.cursor/.env.production'));
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+});
+
 test('planejamento é somente leitura e aplicação detecta mudança concorrente', t => {
   const root = fixture(t); put(root, '.gitignore', 'antes\r\n');
   const plan = planLocalIgnore(root, { outputs: ['generated.md'] });
@@ -250,7 +336,7 @@ test('negação humana é detectada antes de aplicar novas exclusões e permanec
   put(root, '.gitignore', '!/AGENTS.md\n');
   const before = readFileSync(join(root, '.git/info/exclude'), 'utf8');
   const plan = planLocalIgnore(root, { outputs: ['AGENTS.md'] });
-  assert.equal(plan.edits.length, 1);
+  assert.ok(plan.edits.some(edit => edit.path === join(root, '.git/info/exclude')));
   assert.deepEqual(checkLocalIgnore(plan).missing, ['AGENTS.md']);
   assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
   assert.equal(readFileSync(join(root, '.git/info/exclude'), 'utf8'), before);

package/CHANGELOG.md

@@ -4,6 +4,12 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.13 — 2026-11-12
+
+- Proteção de caches de agentes mesmo com negações genéricas no `.gitignore`.
+- Matriz de compatibilidade ampliada para os sete projetos públicos solicitados.
+- Dois exemplos reproduzíveis com produto, design e três specs testadas.
+
 ## 0.0.12 — 2026-11-12
 
 - Entradas e recursos existentes recebem referências em blocos próprios do kit.

package/docs/guides/installation.md

@@ -110,8 +110,10 @@ quando o repositório for iniciado.
 
 O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
 e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
-O `.gitignore` existente e seus arquivos rastreados são preservados;
-uma exceção humana que conflite com essa proteção é informada como conflito.
+O conteúdo do `.gitignore` existente e os arquivos rastreados são preservados.
+Quando há exceções no `.gitignore` da raiz, o kit pode acrescentar um bloco
+limitado ao estado privado dos clientes, sem criar pastas não selecionadas.
+Conflitos detectados nas demais proteções são informados para revisão.
 Nomes próprios de artefatos e arquivos existentes também são conferidos;
 a validação fica restrita ao projeto e aos ignores de seus ancestrais.
 

package/docs/specs/README.md

@@ -18,6 +18,7 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.10](v0.0.10/SPEC.md): release com instalação pelos dois registries e pré-requisitos.
 - [Ecossistema de segurança](security-ecosystem/SPEC.md): fluxos e scanners locais.
 - [Integração sem substituição][additive]: acréscimos em arquivos existentes.
+- [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 
@@ -28,3 +29,4 @@ projeto, siga o [fluxo](../guides/workflow.md) e use os
 [Wiki](../README.md) · [Roadmap](../product/roadmap.md)
 
 [additive]: additive-integration/SPEC.md
+[oss]: real-projects/SPEC.md

package/docs/specs/real-projects/SPEC.md

@@ -0,0 +1,26 @@
+---
+description: Compatibilidade com repositórios públicos e exemplos incrementais.
+status: aprovado
+version: 0.0.13
+---
+
+# Projetos reais e exemplos incrementais
+
+Validar a instalação e manutenção do pacote em commits fixos de projetos reais,
+preservando suas configurações e seu índice Git. Demonstrar o fluxo de produto,
+design e três specs em dois projetos novos, com resultados locais ignorados.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Testar os sete repositórios, com commits registrados. |
+| AC-002 | Testar init repetido, update, sync e preservação nos clones. |
+| AC-003 | Proteger caches ante exceções Git, preservando texto e índice. |
+| AC-004 | Produto e design antes das três specs de cada projeto novo. |
+| AC-005 | Documentar reprodução, limites e saídas ignoradas. |
+| AC-006 | Testes de regressão, pacote e revisão independente passam. |
+
+Os testes de compatibilidade não executam nem compilam as aplicações externas.
+Aprovações de produto e revisão nos exemplos são simuladas. Código de teste é
+versionado; clones, projetos gerados e evidências permanecem fora do Git.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",