@aksp/opencrew 1.6.0 → 1.6.2

package/templates/_opencrew/core/scripts/conferir-fontes/coleta.mjs

@@ -0,0 +1,104 @@
+// Coleta da conferência de fontes: os caminhos que a crew cita. Lê o crew.yaml, os passos
+// (pipeline/steps/*.md) e todos os .md de agents/, em qualquer nível (agentes e tasks).
+// Spec: specs/fase-r1-reparos-1-6-1.md, regras 15 e 16 (repositório do OpenCrew).
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// Marcador de modelo: nome a preencher, não arquivo (R1-06j). Pela ordem: ano (`AAAA-MM-DD`,
+// `YYYY`); par de data ou hora sem letra nem dígito em volta (`DD-MM`, `MM-AA`, `HHMM`); número de
+// ordem (`slide-NN.png`, só em maiúsculas); reticências no lugar de uma pasta. Ficam de fora, para
+// não esconder fonte de verdade: `MM`, `DD` e `AA` sozinhos, `XX` e `[…]`.
+const MARCADORES = [
+  /AAAA|YYYY/i,
+  /(?<![A-Za-z0-9])(?:DD[-_.]?MM|MM[-_.]?DD|MM[-_.]?(?:AA|YY)|(?:AA|YY)[-_.]?MM|HH[-_.h]?MM)(?![A-Za-z0-9])/i,
+  /(?<![A-Za-z0-9])NN(?![A-Za-z0-9])/,
+  /(^|[\\/])(\.\.\.|…)[\\/]/,
+];
+// Comando que termina em nome de arquivo (`node scripts/render.js`) não é caminho.
+const COMANDO = /^(?:node|npx|npm|pnpm|yarn|python3?|pip|git|bash|sh|ls|cd|cat|cp|mv|mkdir|curl)\s/;
+
+function pareceCaminho(t) {
+  if (/[{}<>*$|]/.test(t) || /^https?:/i.test(t) || !/[\\/]/.test(t)) return false;
+  if (COMANDO.test(t) || MARCADORES.some((m) => m.test(t))) return false;
+  return /\.[A-Za-z0-9]{1,5}$/.test(t) || /[\\/]$/.test(t);
+}
+const saidaDeRun = (t) => /(^|[\\/])(output|_build)[\\/]/.test(t);
+
+const ENTRE_CRASES = /`([^`\n]+)`/g;
+// Só espaço e tab antes de `caminho:`: `\s` atravessa linhas e fica lento com muitas em branco.
+const LINHA_DE_CAMINHO = /^([ \t]*(?:-[ \t]*)?caminho:[ \t]*)(.*)$/gm;
+// Linha `- **Writes to**: …` do formato do agente: o que a crew grava (destino), não o que lê.
+const LINHA_DE_DESTINO = /^[ \t]*[-*][ \t]*\*\*Writes to:?\*\*.*$/gim;
+
+/** Caminhos de arquivo citados entre crases (saída de run não é fonte). */
+function entreCrases(texto) {
+  const citados = [...texto.matchAll(ENTRE_CRASES)].map((m) => m[1].trim());
+  return citados.filter((t) => pareceCaminho(t) && !saidaDeRun(t));
+}
+
+/** Valor de `caminho:` — aceita aspas simples ou duplas e comentário `# …` no fim da linha. */
+function valorDeCaminho(resto) {
+  const entreAspas = resto.match(/^(["'])(.*?)\1\s*(?:#.*)?$/);
+  if (entreAspas) return entreAspas[2].trim();
+  return resto.replace(/(^|\s)#.*$/, '').trim();
+}
+
+/** Os `caminho:` declarados em `fontes:` no crew.yaml. */
+function fontesDeclaradas(texto) {
+  const linhas = [...texto.matchAll(LINHA_DE_CAMINHO)];
+  return linhas.map((m) => valorDeCaminho(m[2].trim())).filter(Boolean);
+}
+
+/**
+ * Troca `ref` por `sugestao` só onde a coleta o leu: o texto inteiro de um par de crases e, no
+ * crew.yaml, o valor de uma linha `caminho:` (aspas e comentário ficam). O resto do arquivo —
+ * outro caminho que contém o citado, frontmatter, texto fora de crases — não muda.
+ */
+export function trocarCitacao(texto, { ref, sugestao }, noCrewYaml) {
+  const trocar = (trecho) => trecho.replace(ref, () => sugestao);
+  const novo = texto.replace(ENTRE_CRASES, (tudo, dentro) => (dentro.trim() === ref ? trocar(tudo) : tudo));
+  if (!noCrewYaml) return novo;
+  const naLinha = (tudo, chave, resto) => (valorDeCaminho(resto.trim()) === ref ? chave + trocar(resto) : tudo);
+  return novo.replace(LINHA_DE_CAMINHO, naLinha);
+}
+
+/** Os .md de uma pasta; com `fundo`, também os das subpastas (caminhada própria, Node 20.0). */
+async function arquivosMd(dir, fundo) {
+  let entradas;
+  try { entradas = await readdir(dir, { withFileTypes: true }); } catch { return []; }
+  const achados = [];
+  for (const e of entradas) {
+    const abs = path.join(dir, e.name);
+    if (!e.isDirectory() && e.name.endsWith('.md')) achados.push(abs);
+    if (e.isDirectory() && fundo) achados.push(...await arquivosMd(abs, true));
+  }
+  return achados;
+}
+
+/**
+ * Caminho citado → { arquivos: os arquivos da crew em que ele aparece, destino: true quando só é
+ * citado em linha `Writes to` }.
+ */
+export async function coletar(raiz, crew) {
+  const base = path.resolve(raiz, crew);
+  const crewYaml = path.join(base, 'crew.yaml');
+  const arquivos = [
+    ...(existsSync(crewYaml) ? [crewYaml] : []),
+    ...await arquivosMd(path.join(base, 'pipeline', 'steps'), false),
+    ...await arquivosMd(path.join(base, 'agents'), true),
+  ];
+  const refs = new Map();
+  const anotar = (ref, arquivo, destino) => {
+    if (!refs.has(ref)) refs.set(ref, { arquivos: new Set(), destino: true });
+    refs.get(ref).arquivos.add(arquivo);
+    refs.get(ref).destino &&= destino;
+  };
+  for (const arquivo of arquivos) {
+    const texto = await readFile(arquivo, 'utf8');
+    const lidos = new Set(entreCrases(texto.replace(LINHA_DE_DESTINO, '')));
+    for (const ref of entreCrases(texto)) anotar(ref, arquivo, !lidos.has(ref));
+    if (arquivo === crewYaml) for (const ref of fontesDeclaradas(texto)) anotar(ref, arquivo, false);
+  }
+  return refs;
+}

package/templates/_opencrew/core/scripts/conferir-fontes/relatorio.mjs

@@ -0,0 +1,52 @@
+// Relatório da conferência de fontes e as mensagens ao usuário (PT-BR).
+// Spec: specs/fase-r1-reparos-1-6-1.md, regra 17 e seção 6 (repositório do OpenCrew).
+import path from 'node:path';
+import { barra } from './busca.mjs';
+
+const plural = (n, um, varios) => `${n} ${n === 1 ? um : varios}`;
+
+export const MSG = {
+  nadaACorrigir: 'Nada a corrigir.',
+  corrigidos: (n) => `${plural(n, 'caminho corrigido', 'caminhos corrigidos')} (cópia .bak ao lado de cada arquivo alterado).\n`,
+  semCorrecaoAutomatica: (n) => `Não há correção automática para ${n} pendência(s): escolha um candidato ou corrija o caminho na crew.`,
+  buscaParcial: (limite) => `Procurei só nos primeiros ${limite} itens do projeto; pode existir um arquivo com esse nome que eu não vi.`,
+};
+
+const MAX_NOMES = 20;
+const comCrases = (lista) => lista.map((c) => `\`${c}\``);
+
+/** Os primeiros nomes e, se sobram, quantos: uma pasta grande não pode encher a conversa. */
+function resumida(nomes) {
+  if (nomes.length <= MAX_NOMES) return nomes.join(', ');
+  return [...nomes.slice(0, MAX_NOMES), `… e mais ${nomes.length - MAX_NOMES}`].join(', ');
+}
+
+/** Linha de um caminho que não existe. `aviso` é a frase de busca parcial, ou ''. */
+function linhaDaPendencia(i, onde, aviso) {
+  const inicio = `- ❌ Não encontrei \`${i.ref}\` (${onde})`;
+  const fim = aviso ? `. ${aviso}` : '';
+  const achados = plural(i.candidatos.length, 'candidato', 'candidatos');
+  if (i.sugestao) return `${inicio}. Novo caminho sugerido: \`${i.sugestao}\`${fim}`;
+  if (i.candidatos.length) return `${inicio}. Encontrei ${achados}: ${resumida(comCrases(i.candidatos))}${fim}`;
+  if (i.pasta.length) return `${inicio}. Na pasta esperada existem: ${resumida(i.pasta)}${fim}`;
+  return aviso ? `${inicio}${fim}` : `${inicio} nem nada com esse nome no projeto.`;
+}
+
+function linhaDoAlerta(i, onde) {
+  const sugestao = i.sugestao ? ` Sugestão: \`${i.sugestao}\`` : '';
+  return `- ⚠️ \`${i.ref}\` é um caminho absoluto (não é portátil — quebra em outro computador).${sugestao} (${onde})`;
+}
+
+export function formatar(r) {
+  const aviso = r.buscaParcial ? MSG.buscaParcial(r.limite) : '';
+  const contar = (estado) => r.refs.filter((i) => i.estado === estado).length;
+  const apontados = r.refs.filter((x) => x.estado !== 'ok');
+  const linhas = [`## Conferência de fontes — ${r.crew}`, ''];
+  for (const i of apontados) {
+    const onde = `citado em ${i.citadoEm.map((a) => barra(path.relative(r.raiz, a))).join(', ')}`;
+    linhas.push(i.estado === 'nao-portatil' ? linhaDoAlerta(i, onde) : linhaDaPendencia(i, onde, aviso));
+  }
+  if (apontados.length) linhas.push(''); // sem pendência nem alerta, uma linha em branco só
+  linhas.push(`**Resumo: ${r.refs.length} fontes — ${contar('ok')} ok, ${contar('faltando')} pendentes, ${contar('nao-portatil')} alertas**`, '');
+  return linhas.join('\n');
+}

package/templates/_opencrew/core/scripts/conferir-fontes.mjs

@@ -3,111 +3,67 @@
 // existem. Se foram movidos, sugere o novo caminho (relativo à raiz do projeto); se o nome mudou,
 // lista o que existe na pasta esperada. Nunca apaga nada; só corrige com --corrigir (e .bak).
 // Uso: node _opencrew/core/scripts/conferir-fontes.mjs --crew crews/<nome> [--corrigir]
+// Rode a partir da pasta do projeto (a que tem `_opencrew/`); a crew fica dentro dela.
 // Última linha da saída: FONTES:OK ou FONTES:PENDENTE (o runner lê esta linha).
-// Spec: specs/fase-u2-crew-que-conhece-o-projeto.md (repositório do OpenCrew).
-import { readFile, writeFile, readdir, copyFile } from 'node:fs/promises';
+// Código de saída: 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso (opção faltando, pasta sem
+// `_opencrew/`, crew fora do projeto ou inexistente), sem linha FONTES: e sem escrever nada.
+// Specs: specs/fase-u2-crew-que-conhece-o-projeto.md e specs/fase-r1-reparos-1-6-1.md
+// (repositório do OpenCrew). Módulos em conferir-fontes/: coleta, busca e relatório.
+import { readFile, writeFile, copyFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { erroDeUso, dentroDoProjeto, ehPrincipal } from './comum.mjs';
+import { coletar, trocarCitacao } from './conferir-fontes/coleta.mjs';
+import {
+  LIMITE_DA_BUSCA, barra, ehAbsoluto, temBarraFinal, resolver, indexar, candidatosPorNome, nomesDaPastaEsperada,
+} from './conferir-fontes/busca.mjs';
+import { formatar, MSG } from './conferir-fontes/relatorio.mjs';
 
-const IGNORAR = new Set(['node_modules', 'output', '_opencrew', '_build']);
-const LIMITE_ENTRADAS = 20000;
+export { formatar };
 
-const barra = (p) => p.split(path.sep).join('/');
-const ehAbsoluto = (p) => /^[A-Za-z]:[\\/]/.test(p) || p.startsWith('/');
-
-function pareceCaminho(t) {
-  if (/[{}<>*$|]/.test(t) || /^https?:/i.test(t) || !/[\\/]/.test(t)) return false;
-  return /\.[A-Za-z0-9]{1,5}$/.test(t) || /[\\/]$/.test(t);
-}
-const saidaDeRun = (t) => /(^|[\\/])(output|_build)[\\/]/.test(t);
-
-/** Caminhos citados entre crases no crew.yaml e nos passos, mais as `fontes:` do crew.yaml. */
-async function coletar(raiz, crew) {
-  const refs = new Map();
-  const add = (ref, arquivo) => {
-    if (!refs.has(ref)) refs.set(ref, new Set());
-    refs.get(ref).add(arquivo);
-  };
-  const crewYaml = path.join(raiz, crew, 'crew.yaml');
-  const passos = path.join(raiz, crew, 'pipeline', 'steps');
-  const arquivos = existsSync(crewYaml) ? [crewYaml] : [];
-  if (existsSync(passos)) {
-    for (const f of await readdir(passos)) if (f.endsWith('.md')) arquivos.push(path.join(passos, f));
-  }
-  for (const arquivo of arquivos) {
-    const texto = await readFile(arquivo, 'utf8');
-    for (const m of texto.matchAll(/`([^`\n]+)`/g)) {
-      const t = m[1].trim();
-      if (pareceCaminho(t) && !saidaDeRun(t)) add(t, arquivo);
-    }
-    if (arquivo === crewYaml) {
-      for (const m of texto.matchAll(/^\s*-?\s*caminho:\s*["']?([^"'\n#]+?)["']?\s*$/gm)) add(m[1].trim(), arquivo);
-    }
-  }
-  return refs;
-}
-
-function resolver(raiz, crew, ref) {
-  if (ehAbsoluto(ref)) return existsSync(ref) ? path.resolve(ref) : null;
-  for (const base of [path.join(raiz, crew), raiz]) {
-    const p = path.resolve(base, ref);
-    if (existsSync(p)) return p;
-  }
-  return null;
+/**
+ * Caminho absoluto que existe dentro do projeto: o mesmo caminho, relativo à raiz. A própria raiz
+ * não tem caminho relativo a sugerir.
+ */
+function sugestaoRelativa(raiz, ref, achado) {
+  const relativo = dentroDoProjeto(raiz, achado) ? barra(path.relative(raiz, achado)) : '';
+  return relativo ? relativo + (temBarraFinal(ref) ? '/' : '') : null;
 }
 
-/** Índice nome-do-arquivo → caminhos relativos, ignorando saídas, dependências e pastas ocultas. */
-async function indexar(raiz) {
-  const porNome = new Map();
-  let n = 0;
-  async function walk(dir) {
-    let entradas;
-    try { entradas = await readdir(dir, { withFileTypes: true }); } catch { return; }
-    for (const e of entradas) {
-      if (++n > LIMITE_ENTRADAS) return;
-      if (e.name.startsWith('.') || (e.isDirectory() && IGNORAR.has(e.name))) continue;
-      const abs = path.join(dir, e.name);
-      const chave = e.name.toLowerCase();
-      if (!porNome.has(chave)) porNome.set(chave, []);
-      porNome.get(chave).push(barra(path.relative(raiz, abs)) + (e.isDirectory() ? '/' : ''));
-      if (e.isDirectory()) await walk(abs);
-    }
-  }
-  await walk(raiz);
-  return porNome;
+/**
+ * Caminho que não existe: candidatos com o mesmo nome ou, sem nenhum, o que há na pasta esperada.
+ * Destino (só citado em linha `Writes to`) não ganha sugestão: com a troca, a crew gravaria por
+ * cima do arquivo achado. O candidato é listado e a escolha fica com o usuário. Busca que parou
+ * no limite também não sugere: o único candidato visto pode não ser o único que existe.
+ */
+async function procurar(item, { raiz, crew, indice, destino }) {
+  item.estado = 'faltando';
+  item.candidatos = candidatosPorNome(indice, item.ref);
+  if (item.candidatos.length === 1 && !destino && !indice.parcial) item.sugestao = item.candidatos[0];
+  if (!item.candidatos.length) item.pasta = await nomesDaPastaEsperada(raiz, crew, item.ref);
 }
 
-export async function conferir({ raiz, crew }) {
-  const refs = await coletar(raiz, crew);
+/**
+ * Confere os caminhos que a crew cita. `limite` é o máximo de itens do projeto vistos na busca
+ * por nome; quando a busca para nele, `buscaParcial` é true.
+ */
+export async function conferir({ raiz, crew, limite = LIMITE_DA_BUSCA }) {
   let indice = null;
-  const lista = [];
-  for (const [ref, citado] of refs) {
-    const item = { ref, citadoEm: [...citado], estado: 'ok', sugestao: null, candidatos: [], pasta: [] };
-    const achado = resolver(raiz, crew, ref);
-    if (achado) {
-      if (ehAbsoluto(ref)) {
-        item.estado = 'nao-portatil';
-        const rel = path.relative(raiz, achado);
-        if (!rel.startsWith('..') && !path.isAbsolute(rel)) item.sugestao = barra(rel) + (/[\\/]$/.test(ref) ? '/' : '');
-      }
-    } else {
-      item.estado = 'faltando';
-      indice ??= await indexar(raiz);
-      const nome = path.basename(ref.replace(/[\\/]+$/, '')).toLowerCase();
-      item.candidatos = (indice.get(nome) ?? []).filter((c) => /[\\/]$/.test(ref) === c.endsWith('/'));
-      if (item.candidatos.length === 1) item.sugestao = item.candidatos[0];
-      if (!item.candidatos.length) {
-        const pai = resolver(raiz, crew, path.dirname(ref.replace(/[\\/]+$/, '')));
-        if (pai) {
-          try { item.pasta = (await readdir(pai)).filter((f) => !f.startsWith('.')); } catch { /* não é pasta */ }
-        }
-      }
+  const refs = [];
+  for (const [ref, { arquivos, destino }] of await coletar(raiz, crew)) {
+    const item = { ref, citadoEm: [...arquivos], estado: 'ok', sugestao: null, candidatos: [], pasta: [] };
+    const achado = resolver(raiz, crew, ref, item.citadoEm);
+    if (!achado) {
+      indice ??= await indexar(raiz, limite);
+      await procurar(item, { raiz, crew, indice, destino });
+    } else if (ehAbsoluto(ref)) {
+      item.estado = 'nao-portatil';
+      item.sugestao = sugestaoRelativa(raiz, ref, achado);
     }
-    lista.push(item);
+    refs.push(item);
   }
-  const status = lista.some((i) => i.estado === 'faltando') ? 'PENDENTE' : 'OK';
-  return { crew, raiz, refs: lista, status };
+  const status = refs.some((i) => i.estado === 'faltando') ? 'PENDENTE' : 'OK';
+  return { crew, raiz, refs, status, buscaParcial: Boolean(indice?.parcial), limite };
 }
 
 async function copiaDeSeguranca(arquivo) {
@@ -115,7 +71,10 @@ async function copiaDeSeguranca(arquivo) {
   await copyFile(arquivo, bak);
 }
 
-/** Troca, nos arquivos da crew, cada caminho com sugestão única. @returns quantos caminhos */
+/**
+ * Troca, nos arquivos da crew, cada caminho com sugestão única — só a citação que a coleta leu,
+ * nunca um pedaço de outro texto. @returns quantos caminhos
+ */
 export async function corrigir({ resultado }) {
   const comSugestao = resultado.refs.filter((i) => i.sugestao && i.estado !== 'ok');
   const tocados = new Set();
@@ -126,64 +85,51 @@ export async function corrigir({ resultado }) {
         await copiaDeSeguranca(arquivo);
         tocados.add(arquivo);
       }
-      await writeFile(arquivo, texto.split(item.ref).join(item.sugestao));
+      await writeFile(arquivo, trocarCitacao(texto, item, path.basename(arquivo) === 'crew.yaml'));
     }
   }
   return comSugestao.length;
 }
 
-export function formatar(r) {
-  const rel = (a) => barra(path.relative(r.raiz, a));
-  const linhas = [`## Conferência de fontes — ${r.crew}`, ''];
-  for (const i of r.refs.filter((x) => x.estado !== 'ok')) {
-    const onde = `citado em ${i.citadoEm.map(rel).join(', ')}`;
-    if (i.estado === 'nao-portatil') {
-      linhas.push(`- ⚠️ \`${i.ref}\` é um caminho absoluto (não é portátil — quebra em outro computador).${i.sugestao ? ` Sugestão: \`${i.sugestao}\`` : ''} (${onde})`);
-    } else if (i.sugestao) {
-      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}). Novo caminho sugerido: \`${i.sugestao}\``);
-    } else if (i.candidatos.length) {
-      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}). Encontrei ${i.candidatos.length} candidatos: ${i.candidatos.map((c) => `\`${c}\``).join(', ')}`);
-    } else if (i.pasta.length) {
-      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}). Na pasta esperada existem: ${i.pasta.join(', ')}`);
-    } else {
-      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}) nem nada com esse nome no projeto.`);
-    }
+/** --corrigir: troca o que tem sugestão única e diz quantas pendências ficam sem correção. */
+async function corrigirEAvisar(r, escrever) {
+  const n = await corrigir({ resultado: r });
+  let atual = r;
+  if (n) {
+    escrever(MSG.corrigidos(n));
+    atual = await conferir({ raiz: r.raiz, crew: r.crew });
+    escrever(formatar(atual));
   }
-  const ok = r.refs.filter((i) => i.estado === 'ok').length;
-  const pend = r.refs.filter((i) => i.estado === 'faltando').length;
-  const alertas = r.refs.filter((i) => i.estado === 'nao-portatil').length;
-  linhas.push('', `**Resumo: ${r.refs.length} fontes — ${ok} ok, ${pend} pendentes, ${alertas} alertas**`, '');
-  return linhas.join('\n');
+  const semSugestao = atual.refs.filter((i) => i.estado === 'faltando' && !i.sugestao).length;
+  if (semSugestao) escrever(MSG.semCorrecaoAutomatica(semSugestao));
+  else if (!n) escrever(MSG.nadaACorrigir);
+  return atual;
 }
 
-/** @returns {Promise<number>} 0 = conferiu · 1 = erro de uso */
-export async function main(argv, { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = {}) {
+const USO = 'Uso: node _opencrew/core/scripts/conferir-fontes.mjs --crew crews/<nome> [--corrigir]';
+
+function lerCrew(argv) {
   const i = argv.indexOf('--crew');
-  const crew = i > -1 ? argv[i + 1] : null;
-  if (!crew) {
-    escrever('Uso: node _opencrew/core/scripts/conferir-fontes.mjs --crew crews/<nome> [--corrigir]');
-    return 1;
-  }
-  if (!existsSync(path.join(cwd, crew))) {
-    escrever(`Crew não encontrada: ${crew}`);
+  const valor = i > -1 ? argv[i + 1] : null;
+  return valor && !valor.startsWith('--') ? valor : null;
+}
+
+/** @returns {Promise<number>} 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso */
+export async function main(argv, { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = {}) {
+  const crew = lerCrew(argv);
+  const erro = erroDeUso({ raiz: cwd, faltando: crew ? [] : ['--crew'], crew });
+  if (erro) {
+    escrever(erro);
+    if (!crew) escrever(USO);
     return 1;
   }
   let r = await conferir({ raiz: cwd, crew });
   escrever(formatar(r));
-  if (argv.includes('--corrigir')) {
-    const n = await corrigir({ resultado: r });
-    if (!n) escrever('Nada a corrigir.');
-    else {
-      escrever(`${n} ${n === 1 ? 'caminho corrigido' : 'caminhos corrigidos'} (cópia .bak ao lado de cada arquivo alterado).\n`);
-      r = await conferir({ raiz: cwd, crew });
-      escrever(formatar(r));
-    }
-  }
+  if (argv.includes('--corrigir')) r = await corrigirEAvisar(r, escrever);
   escrever(`FONTES:${r.status}`);
   return 0;
 }
 
-const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMain) {
+if (ehPrincipal(import.meta.url)) {
   main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
 }

package/templates/_opencrew/core/scripts/verificar/argumentos.mjs

@@ -0,0 +1,33 @@
+// Linha de comando do verificador: as opções, os itens `caminho=formato` e a linha de uso.
+// Spec: fase-r1-reparos-1-6-1.md, §3.
+
+// Uma linha só, e sem o texto do status: em erro de uso a saída não tem linha de status.
+export const USO = 'Uso: node _opencrew/core/scripts/verificar.mjs --crew crews/<nome> --arquivo "<caminho=formato>[,<caminho=formato>…]" [--formato blog-post|blog-seo]'
+  + ' — o "=formato" é opcional; o relatório termina em OK, BLOQUEADA ou AGUARDANDO_USUARIO; código de saída: 0 = verificou, 1 = erro de uso';
+
+/**
+ * Opções da linha de comando: `{ crew, formato, arquivos }`. `--arquivo` repetido soma à lista, e
+ * o que vem solto logo depois da lista (sem `--`) é mais um item dela: nenhum arquivo citado fica
+ * sem verificação.
+ */
+export function lerArgs(argv) {
+  const args = { arquivos: [] };
+  let naLista = false;
+  for (let i = 0; i < argv.length; i++) {
+    const opcao = argv[i].match(/^--(crew|arquivo|formato)$/)?.[1];
+    if (opcao && i + 1 < argv.length) {
+      if (opcao === 'arquivo') args.arquivos.push(argv[++i]);
+      else args[opcao] = argv[++i];
+      naLista = opcao === 'arquivo';
+    } else if (naLista && !argv[i].startsWith('--')) args.arquivos.push(argv[i]);
+    else naLista = false;
+  }
+  return args;
+}
+
+/** `caminho=formato` → `{ arquivo, formato }`; "=formato" só vale com minúsculas, dígitos e hífen. */
+export function lerItemDaLista(texto) {
+  const igual = texto.lastIndexOf('=');
+  const formato = igual > 0 ? texto.slice(igual + 1) : '';
+  return /^[a-z0-9-]+$/.test(formato) ? { arquivo: texto.slice(0, igual), formato } : texto;
+}

package/templates/_opencrew/core/scripts/verificar/arquivos.mjs

@@ -0,0 +1,50 @@
+// O que é cada item da lista do verificador: texto, não-texto, pasta, ausente ou texto que não
+// está em UTF-8 (o UTF-16 com a marca de início é lido).
+// Só texto é verificado; em HTML, o texto visível e os links (fase-r1-reparos-1-6-1.md, regra 9).
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { semBom } from './leitura.mjs';
+import { textoDeHtml } from './html.mjs';
+
+const NAO_TEXTO = new Set(
+  '.png .jpg .jpeg .gif .webp .bmp .ico .svg .pdf .doc .docx .xls .xlsx .ods .pptx .mp3 .wav .ogg .mp4 .mov .webm .zip .css .js .json'.split(' '),
+);
+const HTML = new Set(['.html', '.htm']);
+const COM_PECAS = new Set(['.md', '.txt']);
+
+async function tipoNoDisco(caminho) {
+  try {
+    return (await stat(caminho)).isDirectory() ? 'pasta' : 'arquivo';
+  } catch (erro) {
+    if (erro.code === 'ENOENT' || erro.code === 'ENOTDIR') return 'ausente';
+    throw erro;
+  }
+}
+
+/** Texto de um arquivo que começa pela marca de UTF-16 (FF FE ou FE FF); sem a marca, null. */
+function deUtf16(bytes) {
+  const [a, b] = bytes;
+  if (!(a === 0xff && b === 0xfe) && !(a === 0xfe && b === 0xff)) return null;
+  const pares = bytes.subarray(0, bytes.length - (bytes.length % 2));
+  return (a === 0xfe ? pares.swap16() : pares).toString('utf16le');
+}
+
+/**
+ * Lê um item da lista.
+ * @returns {Promise<{ tipo: 'ausente'|'pasta'|'nao-texto'|'nao-utf8'|'texto', texto?: string, comPecas?: boolean }>}
+ *   `comPecas`: a procura de peças só vale para `.md` e `.txt` · `nao-utf8`: `.md`, `.txt`,
+ *   `.html` ou `.htm` com byte nulo e sem a marca de UTF-16
+ */
+export async function lerItem(caminho) {
+  const tipo = await tipoNoDisco(caminho);
+  if (tipo !== 'arquivo') return { tipo };
+  const ext = path.extname(caminho).toLowerCase();
+  if (NAO_TEXTO.has(ext)) return { tipo: 'nao-texto' };
+  const bytes = await readFile(caminho);
+  const deTexto = COM_PECAS.has(ext) || HTML.has(ext);
+  const utf16 = deTexto ? deUtf16(bytes) : null;
+  // Byte nulo é conteúdo binário; em arquivo de texto, é outra codificação.
+  if (utf16 == null && bytes.includes(0)) return { tipo: deTexto ? 'nao-utf8' : 'nao-texto' };
+  const texto = semBom(utf16 ?? bytes.toString('utf8'));
+  return { tipo: 'texto', texto: HTML.has(ext) ? textoDeHtml(texto) : texto, comPecas: COM_PECAS.has(ext) };
+}

package/templates/_opencrew/core/scripts/verificar/html.mjs

@@ -0,0 +1,52 @@
+// Texto de um HTML para as checagens gerais: o texto visível e os valores de `href`, `src` e
+// `alt`. Ficam de fora `<style>`, `<script>`, os comentários e o resto das tags.
+// Uma passada só pelo arquivo, de `<` em `<`: nada aqui recomeça a busca do início.
+
+const ATRIBUTO = /(?:^|\s)(href|src|alt)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/gi;
+const DE_BLOCO = /^\/?(?:p|div|br|hr|li|ul|ol|h[1-6]|tr|td|th|table|section|article|header|footer|main|nav|aside|title|blockquote|figure|figcaption|body|head|html)\b/i;
+const ENTIDADES = { '&nbsp;': ' ', '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'" };
+
+/** Posição logo depois de `marca`, procurada a partir de `de`; o fim do texto se não houver. */
+function depoisDe(html, marca, de) {
+  marca.lastIndex = de;
+  const m = marca.exec(html);
+  return m ? m.index + m[0].length : html.length;
+}
+
+/** Consome o que começa no `<` da posição `abre` e devolve a posição seguinte. */
+function consumir(html, abre, saida) {
+  if (html.startsWith('<!--', abre)) return depoisDe(html, /-->/g, abre + 4);
+  const ehTag = /[a-z/!?]/i.test(html[abre + 1] ?? '');
+  const fecha = ehTag ? html.indexOf('>', abre) : -1;
+  if (fecha < 0) {
+    // "<" solto é texto; tag sem nenhum ">" adiante: o resto todo é texto.
+    const ate = ehTag ? html.length : abre + 1;
+    saida.visivel.push(html.slice(abre, ate));
+    return ate;
+  }
+  const tag = html.slice(abre + 1, fecha);
+  for (const m of tag.matchAll(ATRIBUTO)) {
+    const valor = m[2] ?? m[3] ?? m[4];
+    // `src="data:…"` é o conteúdo de um arquivo embutido, não um link: fica de fora.
+    if (m[1].toLowerCase() === 'alt' || !/^\s*data:/i.test(valor)) saida.valores.push(valor);
+  }
+  if (DE_BLOCO.test(tag)) saida.visivel.push('\n');
+  // Só `<script>` e `<style>`: `<script-x>` e `<style-guia>` são tags comuns.
+  const invisivel = tag.match(/^(script|style)(?=[\s/]|$)/i);
+  return invisivel ? depoisDe(html, new RegExp(`</${invisivel[1]}\\s*>`, 'gi'), fecha + 1) : fecha + 1;
+}
+
+/** Texto visível do HTML, seguido dos valores de `href`, `src` e `alt` (um por linha). */
+export function textoDeHtml(html) {
+  const saida = { visivel: [], valores: [] };
+  let pos = 0;
+  while (pos < html.length) {
+    const abre = html.indexOf('<', pos);
+    if (abre < 0) break;
+    saida.visivel.push(html.slice(pos, abre));
+    pos = consumir(html, abre, saida);
+  }
+  saida.visivel.push(html.slice(pos));
+  const texto = [saida.visivel.join(''), ...saida.valores].join('\n');
+  return texto.replace(/&(?:nbsp|amp|lt|gt|quot|#39);/g, (entidade) => ENTIDADES[entidade]);
+}