@aksp/opencrew 1.10.0 → 1.12.0

package/templates/_opencrew/core/scripts/conserto/achados.mjs

@@ -0,0 +1,158 @@
+// O diagnóstico do conserto: o que falta numa crew para as melhorias do runtime valerem nela.
+// Cada achado tem um código e as linhas, em PT-BR fixo, que o usuário lê. Só leitura.
+// Spec: fase-u4a-conserto-de-crews.md, §4 e regras 5, 6 e 9 (repositório do OpenCrew).
+import path from 'node:path';
+import { lerFrontmatter, semBom } from '../verificar/leitura.mjs';
+import { itensDeProibicao } from '../verificar/proibicoes.mjs';
+import { idDoAgente, lerBruto, listaDe } from './crew.mjs';
+import { lerCsv } from './edicoes.mjs';
+
+const EXPORTACAO = new Set(['pdf', 'csv', 'formatted-post']);
+const plural = (n, um, varios) => (n === 1 ? um : varios);
+const editar = (crew) => `Resolve-se editando a crew: /opencrew edit ${crew.nome}`;
+const irreversivel = (passo) => passo.dados.side_effects === 'irreversible';
+const revisoes = (crew) => crew.passos.filter((p) => p.revisao);
+
+function manifesto(crew) {
+  if (!crew.agentes.length) return null;
+  const { colunas, linhas } = lerCsv(crew.csv);
+  const semNome = (l) => !l.displayName || l.displayName.toLowerCase() === (l.title ?? '').toLowerCase();
+  if (crew.csv !== null && colunas.includes('displayName') && !linhas.some(semNome)) return null;
+  return ['O arquivo de nomes da crew (crew-party.csv) está incompleto: aparece a função no lugar do nome.', 'Para consertar: --aplicar "manifesto"'];
+}
+
+function nomeDeAgente(crew) {
+  const semNome = crew.agentes.filter((a) => String(a.dados.name ?? '').trim().split(/\s+/).filter(Boolean).length < 2);
+  if (!semNome.length) return null;
+  const n = semNome.length;
+  return [
+    `${n} ${plural(n, 'agente', 'agentes')} sem nome de duas palavras.`,
+    ...semNome.map((a) => `${a.id} (name: "${a.dados.name ?? ''}")`),
+    'Para consertar: --aplicar "nome:<agente>=<Nome Sobrenome>" e depois --aplicar "manifesto"',
+  ];
+}
+
+/** Os passos que o verificador mede: do passo de `on_reject` até o anterior à revisão (regra 6). */
+function medidos(crew) {
+  const dentro = new Set();
+  for (const revisao of revisoes(crew)) {
+    const de = crew.passos.findIndex((p) => p.numero === revisao.volta);
+    const ate = crew.passos.indexOf(revisao);
+    if (de >= 0) crew.passos.slice(de, ate).forEach((p) => dentro.add(p));
+  }
+  return crew.passos.filter((p) => dentro.has(p) && p.arquivo && !p.checkpoint && !p.revisao);
+}
+
+const semFormato = (passo) => !passo.dados.format || EXPORTACAO.has(String(passo.dados.format));
+const saidaDe = (passo) => path.posix.basename(String(passo.dados.outputFile ?? passo.citado).replace(/\\/g, '/'));
+
+function formato(crew) {
+  const passos = medidos(crew).filter(semFormato);
+  if (!passos.length) return null;
+  const n = passos.length;
+  return [
+    `${n} ${plural(n, 'passo que a revisão confere não diz', 'passos que a revisão confere não dizem')} o formato do texto.`,
+    'Sem o formato, o redator não recebe o guia desse tipo de texto, e o verificador procura no arquivo peças de rede (legenda, post, título de blog).',
+    `Passos: ${passos.map((p) => `${p.numero} (${saidaDe(p)})`).join(', ')}`,
+    'Para consertar: --aplicar "formato:<passo>=<formato>"',
+  ];
+}
+
+function fontes(crew) {
+  const linhas = semBom(crew.yaml ?? '').split(/\r?\n/);
+  const inicio = linhas.findIndex((l) => /^fontes\s*:/.test(l));
+  const fim = linhas.findIndex((l, i) => i > inicio && /^[^\s#-]/.test(l));
+  const daLista = inicio < 0 ? [] : linhas.slice(inicio + 1, fim < 0 ? linhas.length : fim);
+  if (daLista.some((l) => /^\s*(?:-\s*)?caminho\s*:\s*\S/.test(l))) return null;
+  return [
+    'A crew não registra os arquivos do projeto que ela precisa ler.',
+    'Sem isso, ela escreve sem conhecer o que o projeto já decidiu.',
+    'Para consertar: --aplicar "fonte:<caminho>=<para que>" (um por arquivo ou pasta)',
+  ];
+}
+
+function proibicao(crew) {
+  const pendentes = itensDeProibicao(semBom(crew.memoria ?? '')).filter((i) => i.pendente);
+  if (!pendentes.length) return null;
+  const n = pendentes.length;
+  return [
+    `${n} ${plural(n, 'proibição', 'proibições')} sem trecho entre aspas: o verificador não consegue barrar.`,
+    ...pendentes.map((i) => `${i.n}. ${i.texto}`),
+    'Para consertar: --aplicar "proibicao:<n>=<trecho>" ou --aplicar "proibicao:<n>=revisao-humana"',
+  ];
+}
+
+/** A skill instalada no projeto declara `side_effects: irreversible`? (regra 9) */
+function publica(raiz, skill) {
+  const texto = lerBruto(path.join(raiz, 'skills', skill, 'SKILL.md'));
+  return texto !== null && lerFrontmatter(semBom(texto))?.side_effects === 'irreversible';
+}
+
+function semMarca(crew) {
+  const doPasso = (passo) => {
+    const agente = crew.agentes.find((a) => a.id === idDoAgente(passo));
+    const skills = [...listaDe(agente?.bruto, 'skills'), ...listaDe(passo.bruto, 'skills_needed')];
+    const skill = skills.find((s) => /^[A-Za-z0-9._-]+$/.test(s) && publica(crew.raiz, s));
+    return skill ? `Passo ${passo.numero} — agente ${agente?.id ?? idDoAgente(passo)}, skill ${skill}` : null;
+  };
+  const linhas = crew.passos.filter((p) => p.arquivo && !p.checkpoint && !irreversivel(p)).map(doPasso).filter(Boolean);
+  if (!linhas.length) return null;
+  const n = linhas.length;
+  return [
+    `${n} ${plural(n, 'passo', 'passos')} de agente que tem ferramenta de publicar ou enviar, sem a marca de passo irreversível.`,
+    ...linhas,
+    'Se o passo publica ou envia: --aplicar "irreversivel:<passo>"',
+  ];
+}
+
+function semRevisao(crew) {
+  if (revisoes(crew).length || !crew.passos.length) return null;
+  return ['A crew não tem passo de revisão: nada é conferido antes de chegar a você.', editar(crew)];
+}
+
+/** Posição da última revisão e do primeiro checkpoint depois dela (-1 quando não há). */
+function fecho(crew) {
+  const revisao = crew.passos.indexOf(revisoes(crew).at(-1));
+  const aprovacao = crew.passos.findIndex((p, i) => i > revisao && p.checkpoint);
+  return { revisao, aprovacao };
+}
+
+function semAprovacaoFinal(crew) {
+  const { revisao, aprovacao } = fecho(crew);
+  if (revisao < 0 || aprovacao >= 0) return null;
+  return ['Depois da revisão não há um ponto de aprovação seu.', editar(crew)];
+}
+
+function publicaAntes(crew) {
+  const { revisao, aprovacao } = fecho(crew);
+  if (revisao < 0) return null;
+  const limite = aprovacao >= 0 ? aprovacao : revisao;
+  const cedo = crew.passos.filter((p, i) => i < limite && irreversivel(p)).map((p) => p.numero);
+  if (!cedo.length) return null;
+  const quem = cedo.length === 1 ? `O passo ${cedo[0]} publica ou envia` : `Os passos ${cedo.join(', ')} publicam ou enviam`;
+  return [`${quem} antes da revisão e da sua aprovação final.`, 'Enquanto estiver assim, o que sai não passou pela revisão.', editar(crew)];
+}
+
+function passoFaltando(crew) {
+  const semArquivo = crew.passos.filter((p) => !p.arquivo).map((p) => `O passo ${p.numero} cita ${p.citado || 'um arquivo sem nome'}, que não existe.`);
+  const existe = (numero) => crew.passos.some((p) => p.numero === numero);
+  const semAlvo = revisoes(crew).filter((p) => !existe(p.volta)).map((p) => `O passo ${p.numero} manda voltar ao passo ${p.volta ?? p.dados.on_reject}, que não existe.`);
+  const linhas = [...semArquivo, ...semAlvo];
+  return linhas.length ? ['A sequência de passos cita o que não existe.', ...linhas, editar(crew)] : null;
+}
+
+// A ordem em que os achados aparecem (§4 da spec).
+const CONFERENCIAS = [
+  ['nome-de-agente', nomeDeAgente], ['manifesto', manifesto], ['formato', formato], ['fontes', fontes],
+  ['proibicao', proibicao], ['irreversivel', semMarca], ['sem-revisao', semRevisao],
+  ['sem-aprovacao-final', semAprovacaoFinal], ['publica-antes', publicaAntes], ['passo-faltando', passoFaltando],
+];
+
+/**
+ * Os achados de uma crew, na ordem da spec.
+ * @param {object} crew o que `lerCrew` devolveu
+ * @returns {Array<{ codigo: string, linhas: string[] }>} a primeira linha é o título do achado
+ */
+export function diagnosticar(crew) {
+  return CONFERENCIAS.map(([codigo, conferir]) => ({ codigo, linhas: conferir(crew) })).filter((a) => a.linhas);
+}

package/templates/_opencrew/core/scripts/conserto/aplicar.mjs

@@ -0,0 +1,156 @@
+// `--aplicar`: valida todos os itens, monta as mudanças em memória e só então grava — cada arquivo
+// alterado ganha antes uma cópia `.bak` (a que já existe fica). Um item recusado: nada é gravado.
+// Spec: fase-u4a-conserto-de-crews.md, regras 1 a 4 e 7 (repositório do OpenCrew).
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { dentroDoProjeto } from '../comum.mjs';
+import { lerFrontmatter, semAcento, semBom } from '../verificar/leitura.mjs';
+import { ehRevisaoHumana, itensDeProibicao, lerLinha } from '../verificar/proibicoes.mjs';
+import { comChave, comFonte, comSufixo, comTitulo, montarCsv } from './edicoes.mjs';
+import { erroAntesDeGravar } from './gravar.mjs';
+
+const MSG = {
+  semValor: (item) => `Sobra ou falta valor em --aplicar "${item.escrito}". Veja os itens com --ajuda.`,
+  semPasso: (item) => `Passo não encontrado em --aplicar "${item.escrito}".`,
+  checkpoint: (n, item) => `O passo ${n} é um ponto de aprovação: --aplicar "${item.escrito}" não vale para ele.`,
+  semFrontmatter: (n) => `Não altero o passo ${n}: o arquivo não tem o bloco de campos no começo (entre linhas ---), ou o campo ocupa mais de uma linha. Ajuste pela edição da crew.`,
+  fontesNaLinha: 'Não altero o `crew.yaml`: a lista `fontes:` está escrita numa linha só. Ajuste pela edição da crew.',
+  trechoIlegivel: 'O verificador não consegue ler esse trecho como trava: use até 200 caracteres, sem crase nem aspas.',
+  semFormato: (id) => `Formato "${id}" não encontrado em \`_opencrew/best-practices.local/\` nem em \`_opencrew/core/best-practices/\`.`,
+  fonteAbsoluta: (c) => `A fonte tem de ser um caminho relativo à pasta do projeto: ${c}`,
+  fonteFora: (c) => `Caminho fora do projeto: ${c}`,
+  fonteAusente: (c) => `Não encontrei no projeto: ${c}`,
+  semAgentes: 'A crew não tem agentes em `agents/`: não há de onde refazer o crew-party.csv.',
+  semAgente: (item) => `Agente não encontrado em --aplicar "${item.escrito}".`,
+  nomeCurto: 'O nome do agente tem duas palavras (nome e sobrenome), sem aspas.',
+  jaTemNome: (id, nome) => `O agente ${id} já tem nome: ${nome}. Para trocar, use /opencrew edit.`,
+  semFrontmatterDoAgente: (id) => `Não altero o agente ${id}: o arquivo não tem o bloco de campos no começo (entre linhas ---), ou o campo name ocupa mais de uma linha.`,
+  semItem: (item) => `Item de proibição não encontrado em --aplicar "${item.escrito}".`,
+  jaResolvido: (n) => `A proibição ${n} já tem trecho entre aspas ou já está marcada como revisão humana.`,
+  comAspas: 'O trecho da trava não pode ter aspas duplas.',
+  foraDoItem: (n, trecho) => `O trecho "${trecho}" não aparece na proibição ${n}.`,
+};
+
+/** As mudanças em memória: por arquivo, o texto do disco (`antes`) e o texto novo (`depois`). */
+function novoPlano() {
+  const arquivos = new Map();
+  const plano = {
+    arquivos,
+    trocas: 0,
+    texto: (arquivo, doDisco) => (arquivos.has(arquivo) ? arquivos.get(arquivo).depois : doDisco),
+    /** Texto igual ao que já está no plano não conta como troca. Devolve null (não há erro). */
+    trocar(arquivo, doDisco, depois) {
+      if (depois === plano.texto(arquivo, doDisco)) return null;
+      arquivos.set(arquivo, { antes: arquivos.has(arquivo) ? arquivos.get(arquivo).antes : doDisco, depois });
+      plano.trocas += 1;
+      return null;
+    },
+  };
+  return plano;
+}
+
+function passoDe(crew, item) {
+  const passo = /^\d+$/.test(item.alvo) ? crew.passos.find((p) => p.numero === Number(item.alvo)) : null;
+  if (!passo?.arquivo) return { erro: MSG.semPasso(item) };
+  return passo.checkpoint ? { erro: MSG.checkpoint(passo.numero, item) } : { passo };
+}
+
+const formatoExiste = (raiz, id) => [['best-practices.local'], ['core', 'best-practices']].some((p) => existsSync(path.join(raiz, '_opencrew', ...p, `${id}.md`)));
+
+function formato(crew, item, plano) {
+  const { passo, erro } = passoDe(crew, item);
+  if (erro) return erro;
+  if (!/^[a-z0-9-]+$/.test(item.valor) || !formatoExiste(crew.raiz, item.valor)) return MSG.semFormato(item.valor);
+  const novo = comChave(plano.texto(passo.arquivo, passo.bruto), 'format', item.valor, 'agent');
+  return novo === null ? MSG.semFrontmatter(passo.numero) : plano.trocar(passo.arquivo, passo.bruto, novo);
+}
+
+function irreversivel(crew, item, plano) {
+  const { passo, erro } = passoDe(crew, item);
+  if (erro) return erro;
+  if (item.valor) return MSG.semValor(item);
+  const inline = comChave(plano.texto(passo.arquivo, passo.bruto), 'execution', 'inline');
+  const marcado = inline === null ? null : comChave(inline, 'side_effects', 'irreversible');
+  return marcado === null ? MSG.semFrontmatter(passo.numero) : plano.trocar(passo.arquivo, passo.bruto, marcado);
+}
+
+const ehAbsoluto = (c) => path.isAbsolute(c) || /^[A-Za-z]:/.test(c) || /^[\\/]/.test(c);
+
+function fonte(crew, item, plano) {
+  if (!item.alvo || !item.valor) return MSG.semValor(item);
+  if (ehAbsoluto(item.alvo)) return MSG.fonteAbsoluta(item.alvo);
+  if (!dentroDoProjeto(crew.raiz, item.alvo)) return MSG.fonteFora(item.alvo);
+  if (!existsSync(path.resolve(crew.raiz, item.alvo))) return MSG.fonteAusente(item.alvo);
+  const caminho = item.alvo.replace(/\\/g, '/');
+  const novo = comFonte(plano.texto(crew.arquivos.yaml, crew.yaml), caminho, item.valor);
+  return novo === null ? MSG.fontesNaLinha : plano.trocar(crew.arquivos.yaml, crew.yaml, novo);
+}
+
+function manifesto(crew, item, plano) {
+  if (item.alvo || item.valor) return MSG.semValor(item);
+  if (!crew.agentes.length) return MSG.semAgentes;
+  const { csv } = crew.arquivos;
+  // Os agentes como ficam depois dos itens anteriores desta chamada (um `nome:` antes do `manifesto`).
+  const agentes = crew.agentes.map((a) => ({ ...a, dados: lerFrontmatter(semBom(plano.texto(a.arquivo, a.bruto))) ?? {} }));
+  return plano.trocar(csv, crew.csv, montarCsv(agentes, plano.texto(csv, crew.csv)));
+}
+
+const palavras = (nome) => String(nome ?? '').trim().split(/\s+/).filter(Boolean);
+
+/** O nome de duas palavras no `name:` do agente e no título do arquivo (a primeira linha `# …`). */
+function nome(crew, item, plano) {
+  const agente = crew.agentes.find((a) => a.id === item.alvo);
+  if (!agente) return MSG.semAgente(item);
+  if (palavras(item.valor).length < 2 || /["\r\n]/.test(item.valor)) return MSG.nomeCurto;
+  if (agente.dados.name === item.valor) return null;
+  if (palavras(agente.dados.name).length >= 2) return MSG.jaTemNome(agente.id, agente.dados.name);
+  const comNome = comChave(plano.texto(agente.arquivo, agente.bruto), 'name', JSON.stringify(item.valor));
+  if (comNome === null) return MSG.semFrontmatterDoAgente(agente.id);
+  return plano.trocar(agente.arquivo, agente.bruto, comTitulo(comNome, item.valor));
+}
+
+/** Por que o item não pode ganhar a marca pedida, ou null. */
+function recusaDaProibicao(alvo, item, humano) {
+  if (!alvo.pendente) return MSG.jaResolvido(alvo.n);
+  if (humano) return null;
+  if (item.valor.includes('"')) return MSG.comAspas;
+  return semAcento(alvo.texto).includes(semAcento(item.valor)) ? null : MSG.foraDoItem(alvo.n, item.valor);
+}
+
+function proibicao(crew, item, plano) {
+  const { memoria } = crew.arquivos;
+  const texto = plano.texto(memoria, crew.memoria) ?? '';
+  const alvo = itensDeProibicao(semBom(texto)).find((i) => String(i.n) === item.alvo);
+  if (!alvo || !item.valor) return MSG.semItem(item);
+  const humano = item.valor === 'revisao-humana';
+  const linha = texto.split(/\r?\n/)[alvo.indice];
+  if (humano ? ehRevisaoHumana(linha) : linha.includes(`"${item.valor}"`)) return null;
+  const recusa = recusaDaProibicao(alvo, item, humano);
+  if (recusa) return recusa;
+  const novo = comSufixo(texto, alvo.indice, humano ? ' (revisão humana)' : ` — trava: "${item.valor}"`);
+  // A trava só vale se o verificador a lê de volta, igual (crase, aspa solta e trecho longo quebram a leitura).
+  const lido = lerLinha(novo.split(/\r?\n/)[alvo.indice]);
+  if (!humano && !(lido.proibidos.includes(item.valor) && lido.preferidos.length === 0)) return MSG.trechoIlegivel;
+  return plano.trocar(memoria, crew.memoria, novo);
+}
+
+const ACOES = { manifesto, nome, formato, fonte, proibicao, irreversivel };
+
+/**
+ * Valida os itens e monta as mudanças, sem gravar.
+ * @returns {{ erro: string } | { mudancas: Array<{ arquivo, antes, depois }>, iguais: string[] }}
+ *   `iguais`: os itens que não mudaram nada (já estava assim)
+ */
+export function planejar(crew, itens) {
+  const plano = novoPlano();
+  const iguais = [];
+  for (const item of itens) {
+    const antes = plano.trocas;
+    const erro = ACOES[item.tipo](crew, item, plano);
+    if (erro) return { erro };
+    if (plano.trocas === antes) iguais.push(item.escrito);
+  }
+  const mudancas = [...plano.arquivos].map(([arquivo, m]) => ({ arquivo, ...m })).filter((m) => m.depois !== m.antes);
+  const erro = erroAntesDeGravar(crew.raiz, mudancas);
+  return erro ? { erro } : { mudancas, iguais };
+}

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

@@ -0,0 +1,51 @@
+// Linha de comando do `conserto.mjs`: a crew, os itens de `--aplicar` e a ajuda.
+// Spec: fase-u4a-conserto-de-crews.md, §3 (repositório do OpenCrew).
+
+export const USO = 'Uso: node _opencrew/core/scripts/conserto.mjs --crew "crews/<crew>" [--aplicar "<item>" …]';
+export const AJUDA = [
+  USO,
+  'Sem --aplicar: só lê a crew e mostra o que há para consertar.',
+  'Itens de --aplicar (cada gravação deixa uma cópia .bak do arquivo de antes):',
+  '  manifesto                        refaz o crew-party.csv a partir dos agentes',
+  '  nome:<agente>=<Nome Sobrenome>   grava o nome de duas palavras no arquivo do agente',
+  '  formato:<passo>=<formato>        grava o formato do texto no passo',
+  '  fonte:<caminho>=<para que>       registra um arquivo ou pasta do projeto em fontes:',
+  '  proibicao:<n>=<trecho>           o trecho do item n vira trava do verificador',
+  '  proibicao:<n>=revisao-humana     o item n fica para o revisor',
+  '  irreversivel:<passo>             marca o passo que publica ou envia',
+];
+
+export const TIPOS = ['manifesto', 'nome', 'formato', 'fonte', 'proibicao', 'irreversivel'];
+const OPCAO = /^--(crew|aplicar|ajuda)(?:=(.*))?$/s;
+const ITEM = /^([a-z-]+)(?::([^=]*))?(?:=(.*))?$/s;
+
+/** Texto que veio da linha de comando e volta numa mensagem: uma linha só, até 200 caracteres. */
+export const limpar = (valor) => String(valor).replace(/\s+/g, ' ').trim().slice(0, 200);
+
+/**
+ * `argv` → `{ crew, itens, ajuda, estranho }`. Opção vale como `--nome valor` e `--nome=valor`;
+ * `--aplicar` pode repetir. `estranho`: o primeiro argumento que não é opção conhecida.
+ */
+export function lerArgs(argv) {
+  const args = { crew: undefined, itens: [], ajuda: false, estranho: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const [, nome, colado] = argv[i].match(OPCAO) ?? [];
+    if (!nome) args.estranho ??= argv[i];
+    else if (nome === 'ajuda') args.ajuda = true;
+    else {
+      const valor = colado ?? (i + 1 < argv.length ? argv[++i] : '');
+      if (nome === 'crew') args.crew = valor;
+      else args.itens.push(valor);
+    }
+  }
+  return args;
+}
+
+/**
+ * Um item de `--aplicar`: `tipo[:alvo][=valor]`.
+ * @returns {{ tipo: string, alvo: string, valor: string, escrito: string } | null} null = tipo desconhecido
+ */
+export function lerItem(escrito) {
+  const [, tipo, alvo = '', valor = ''] = String(escrito).match(ITEM) ?? [];
+  return TIPOS.includes(tipo) ? { tipo, alvo: alvo.trim(), valor: valor.trim(), escrito: limpar(escrito) } : null;
+}

package/templates/_opencrew/core/scripts/conserto/crew.mjs

@@ -0,0 +1,126 @@
+// Leitura de uma crew para o conserto: `crew.yaml`, os passos do pipeline, os agentes, o manifesto
+// e a memória. A leitura é tolerante (aceita as formas que versões antigas gravaram) e nunca grava.
+// Spec: fase-u4a-conserto-de-crews.md, regra 5 (repositório do OpenCrew).
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { realDentroDe } from '../comum.mjs';
+import { lerFrontmatter, semBom } from '../verificar/leitura.mjs';
+
+/** O texto do arquivo como está no disco (com BOM e fim de linha), ou null quando não existe. */
+export function lerBruto(arquivo) {
+  return existsSync(arquivo) && statSync(arquivo).isFile() ? readFileSync(arquivo, 'utf8') : null;
+}
+
+/** Valor de uma linha de YAML simples: sem aspas e sem o comentário do fim. */
+const limpo = (valor) => valor.replace(/\s+#.*$/, '').trim().replace(/^(["'])(.*)\1$/, '$2');
+const PAR = /^\s*(?:-\s+)?([A-Za-z_]+)\s*:\s*(.*)$/;
+
+/** As entradas de `steps:` do `pipeline.yaml`, na ordem: `{ step, file, on_reject, … }`. */
+export function entradasDoPipeline(texto) {
+  const entradas = [];
+  let dentro = false;
+  for (const linha of semBom(texto ?? '').split(/\r?\n/)) {
+    if (!linha.trim() || /^\s*#/.test(linha)) continue; // linha em branco e comentário não mudam a leitura
+    if (/^\S/.test(linha) && !/^-\s/.test(linha)) dentro = /^steps\s*:/.test(linha);
+    else if (dentro) anotar(entradas, linha);
+  }
+  return entradas.map(({ coluna: _coluna, ...entrada }) => entrada);
+}
+
+/** Só valem as chaves da própria entrada (na coluna da primeira): chave de um bloco de dentro não conta. */
+function anotar(entradas, linha) {
+  const item = linha.match(/^(\s*-\s+)(.*)$/);
+  if (item) entradas.push({ coluna: item[1].length });
+  const atual = entradas.at(-1);
+  if (!atual || (!item && linha.match(/^\s*/)[0].length !== atual.coluna)) return;
+  const par = linha.match(PAR);
+  if (par) atual[par[1]] = limpo(par[2]);
+  else if (item) atual.file = limpo(item[2]);
+}
+
+/**
+ * Onde está o arquivo do passo: com ou sem `steps/` na frente (regra 5). O passo é sempre um
+ * arquivo de dentro da crew: caminho absoluto ou com `..` não é lido nem alterado.
+ */
+function arquivoDoPasso(pasta, citado) {
+  const partes = citado.split(/[\\/]/);
+  if (path.isAbsolute(citado) || /^[A-Za-z]:/.test(citado) || partes.includes('..')) return null;
+  const candidatos = [['pipeline', 'steps', citado], ['pipeline', citado], [citado]];
+  const achado = candidatos.map((c) => path.join(pasta, ...c)).find((c) => realDentroDe(pasta, c) && lerBruto(c) !== null);
+  return achado ?? null;
+}
+
+/** Número inteiro escrito como número ou entre aspas; senão, null. */
+const inteiro = (v) => (/^\d+$/.test(String(v ?? '').trim()) ? Number(v) : null);
+
+function passoDe(pasta, entrada, posicao) {
+  const arquivo = entrada.file ? arquivoDoPasso(pasta, entrada.file) : null;
+  const bruto = arquivo ? lerBruto(arquivo) : null;
+  const dados = (bruto && lerFrontmatter(semBom(bruto))) || {};
+  const volta = dados.on_reject ?? entrada.on_reject;
+  return {
+    numero: inteiro(entrada.step) ?? posicao + 1,
+    citado: entrada.file ?? '',
+    arquivo,
+    bruto,
+    dados,
+    checkpoint: dados.type === 'checkpoint',
+    revisao: volta !== undefined && volta !== '',
+    volta: inteiro(volta),
+  };
+}
+
+/** Sem `pipeline.yaml` (ou sem entradas), os passos são os arquivos de `pipeline/steps`, em ordem. */
+function entradasDaPasta(pasta) {
+  const dir = path.join(pasta, 'pipeline', 'steps');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith('.md')).sort().map((file) => ({ file }));
+}
+
+/** Lista de um frontmatter: `chave: [a, b]` ou um item `- a` por linha. */
+export function listaDe(bruto, chave) {
+  const fm = semBom(bruto ?? '').match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? '';
+  const linhas = fm.split(/\r?\n/);
+  const i = linhas.findIndex((l) => new RegExp(`^${chave}\\s*:`).test(l));
+  if (i < 0) return [];
+  const naLinha = linhas[i].slice(linhas[i].indexOf(':') + 1).trim();
+  if (naLinha) return naLinha.replace(/^\[|\]$/g, '').split(',').map(limpo).filter(Boolean);
+  const itens = [];
+  for (let n = i + 1; n < linhas.length && /^\s*-\s+/.test(linhas[n]); n++) itens.push(limpo(linhas[n].replace(/^\s*-\s+/, '')));
+  return itens;
+}
+
+function agentesDe(pasta) {
+  const dir = path.join(pasta, 'agents');
+  if (!existsSync(dir)) return [];
+  const arquivos = readdirSync(dir).filter((f) => f.endsWith('.agent.md')).sort();
+  return arquivos.map((f) => {
+    const bruto = lerBruto(path.join(dir, f));
+    return { id: f.slice(0, -'.agent.md'.length), arquivo: path.join(dir, f), bruto, dados: lerFrontmatter(semBom(bruto)) ?? {} };
+  });
+}
+
+/** O `id` do agente de um passo: o último segmento do que está em `agent:` (regra 5). */
+export const idDoAgente = (passo) => String(passo.dados.agent ?? '').split(/[\\/]/).at(-1);
+
+/**
+ * A crew como está no disco.
+ * @param {string} raiz pasta do projeto · @param {string} crew `crews/<nome>`, como veio em `--crew`
+ */
+export function lerCrew(raiz, crew) {
+  const pasta = path.resolve(raiz, crew);
+  const arquivo = (...partes) => path.join(pasta, ...partes);
+  const doPipeline = entradasDoPipeline(lerBruto(arquivo('pipeline', 'pipeline.yaml')));
+  const entradas = doPipeline.length ? doPipeline : entradasDaPasta(pasta);
+  return {
+    raiz,
+    pasta,
+    nome: path.basename(pasta),
+    yaml: lerBruto(arquivo('crew.yaml')),
+    passos: entradas.map((e, i) => passoDe(pasta, e, i)),
+    agentes: agentesDe(pasta),
+    csv: lerBruto(arquivo('crew-party.csv')),
+    memoria: lerBruto(arquivo('_memory', 'memories.md')),
+    arquivos: { yaml: arquivo('crew.yaml'), csv: arquivo('crew-party.csv'), memoria: arquivo('_memory', 'memories.md') },
+  };
+}

package/templates/_opencrew/core/scripts/conserto/edicoes.mjs

@@ -0,0 +1,133 @@
+// As edições do conserto, como funções de texto: cada uma muda só a linha que o item pede e
+// devolve o resto igual, byte a byte (fim de linha, BOM, comentários e ordem das chaves).
+// Spec: fase-u4a-conserto-de-crews.md, regras 3 e 4 (repositório do OpenCrew).
+
+import { lerFrontmatter, semBom } from '../verificar/leitura.mjs';
+
+const BOM = String.fromCharCode(0xfeff);
+const emLinhas = (texto) => texto.split(/(?<=\n)/);
+const fimDe = (linha) => linha.match(/\r?\n$/)?.[0] ?? '';
+const eolDe = (texto) => (texto.includes('\r\n') ? '\r\n' : '\n');
+const ehCerca = (linha) => /^\uFEFF?---\s*$/.test(linha);
+
+const semAspas = (v) => v.replace(/\r?\n$/, '').replace(/\s+#.*$/, '').trim().replace(/^(["'])(.*)\1$/, '$2');
+
+/** A linha da chave tem o valor nela mesma? ("não" quando ele continua nas linhas de baixo) */
+function valorNaLinha(linhas, i, fim) {
+  const valor = semAspas(linhas[i].slice(linhas[i].indexOf(':') + 1));
+  const continua = i + 1 < fim && /^(?:\s+\S|-\s)/.test(linhas[i + 1]);
+  return valor !== '' && !/^[>|][+-]?$/.test(valor) && !continua;
+}
+
+/**
+ * O frontmatter do arquivo com `chave: valor`. A linha da chave é trocada no lugar; se não existe,
+ * entra depois da linha `depoisDe:` ou, na falta dela, no fim do frontmatter. Valor que já é o
+ * pedido (com aspas ou comentário): o texto volta igual.
+ * @returns {string|null} null quando o arquivo não tem frontmatter, ou quando o valor da chave
+ *   ocupa mais de uma linha (o script não reescreve um bloco)
+ */
+export function comChave(texto, chave, valor, depoisDe) {
+  const linhas = emLinhas(texto);
+  const fim = linhas.findIndex((l, i) => i > 0 && ehCerca(l));
+  if (!linhas.length || !ehCerca(linhas[0]) || fim < 0 || !lerFrontmatter(semBom(texto))) return null;
+  const eol = fimDe(linhas[0]) || eolDe(texto);
+  const acha = (nome) => linhas.findIndex((l, i) => i > 0 && i < fim && new RegExp(`^${nome}\\s*:`).test(l));
+  const nova = `${chave}: ${valor}${eol}`;
+  const atual = acha(chave);
+  if (atual < 0) linhas.splice(depoisDe && acha(depoisDe) >= 0 ? acha(depoisDe) + 1 : fim, 0, nova);
+  else if (!valorNaLinha(linhas, atual, fim)) return null;
+  else if (semAspas(linhas[atual].slice(linhas[atual].indexOf(':') + 1)) === semAspas(valor)) return texto;
+  else linhas[atual] = nova;
+  return linhas.join('');
+}
+
+/** O arquivo com `# titulo` na primeira linha de título de nível 1 depois do frontmatter; sem ela, o texto igual. */
+export function comTitulo(texto, titulo) {
+  const linhas = emLinhas(texto);
+  const fim = ehCerca(linhas[0] ?? '') ? linhas.findIndex((l, i) => i > 0 && ehCerca(l)) : -1;
+  const i = linhas.findIndex((l, n) => n > fim && /^# /.test(l));
+  if (i >= 0) linhas[i] = `# ${titulo}${fimDe(linhas[i])}`;
+  return linhas.join('');
+}
+
+/** Valor de YAML: como está quando é simples; entre aspas quando tem `: `, `#` ou aspas. */
+const escrito = (valor) => (/^[^\s"'#[\]{}&*!|>%@`-][^"#\r\n]*$/u.test(valor) && !/:\s|\s$/.test(valor) ? valor : JSON.stringify(valor));
+const normal = (c) => c.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+const mesmoCaminho = (a, b) => normal(a) === normal(b);
+const CAMINHO = /^[ \t]*(?:-[ \t]*)?caminho:[ \t]*(.*)$/;
+
+/** Onde começa e acaba a lista de `fontes:` (a linha da chave e a última linha do bloco), ou null. */
+function blocoDeFontes(linhas) {
+  const inicio = linhas.findIndex((l) => /^fontes\s*:/.test(l.replace(BOM, '')));
+  if (inicio < 0) return null;
+  let fim = inicio;
+  for (let i = inicio + 1; i < linhas.length && (!linhas[i].trim() || /^(?:\s|-\s)/.test(linhas[i])); i++) {
+    if (linhas[i].trim()) fim = i;
+  }
+  return { inicio, fim };
+}
+
+/**
+ * O `crew.yaml` com mais uma fonte, no formato que o Build grava. Fonte que já está: texto igual.
+ * @returns {string|null} null quando `fontes:` está escrita numa linha só (`fontes: [{…}]`): o
+ *   script não reescreve essa forma
+ */
+export function comFonte(texto, caminho, paraQue) {
+  const eol = eolDe(texto);
+  const linhas = emLinhas(texto);
+  const bloco = blocoDeFontes(linhas);
+  const naLinha = bloco ? semAspas(linhas[bloco.inicio].slice(linhas[bloco.inicio].indexOf(':') + 1)) : '';
+  if (naLinha && naLinha !== '[]') return null;
+  const daLista = bloco ? linhas.slice(bloco.inicio + 1, bloco.fim + 1).map((l) => l.replace(/\r?\n$/, '')) : [];
+  if (daLista.some((l) => CAMINHO.test(l) && mesmoCaminho(semAspas(l.match(CAMINHO)[1]), caminho))) return texto;
+  const recuo = daLista.find((l) => /^\s*-\s/.test(l))?.match(/^\s*/)[0] ?? '  ';
+  const item = [`${recuo}- caminho: ${escrito(caminho)}${eol}`, `${recuo}  para_que: ${escrito(paraQue)}${eol}`];
+  if (!bloco) return `${texto}${texto && !fimDe(texto) ? eol : ''}${texto.trim() ? eol : ''}fontes:${eol}${item.join('')}`;
+  if (naLinha === '[]') linhas[bloco.inicio] = `fontes:${fimDe(linhas[bloco.inicio]) || eol}`;
+  if (!fimDe(linhas[bloco.fim])) linhas[bloco.fim] += eol;
+  linhas.splice(bloco.fim + 1, 0, ...item);
+  return linhas.join('');
+}
+
+/** A linha `indice` com `sufixo` no fim, antes do fim de linha. */
+export function comSufixo(texto, indice, sufixo) {
+  const linhas = emLinhas(texto);
+  const fim = fimDe(linhas[indice]);
+  linhas[indice] = `${linhas[indice].slice(0, linhas[indice].length - fim.length).trimEnd()}${sufixo}${fim}`;
+  return linhas.join('');
+}
+
+/** Os campos de uma linha de CSV: aspas duplas protegem vírgula e espaço; `""` é uma aspa. */
+function campos(linha) {
+  const saida = [];
+  const rx = /(?:^|,)(?:"((?:[^"]|"")*)"|([^,]*))/g;
+  for (const m of linha.matchAll(rx)) saida.push(m[1] !== undefined ? m[1].replace(/""/g, '"') : m[2].trim());
+  return saida;
+}
+
+/** O manifesto lido: as colunas e uma linha por agente (`{ coluna: valor }`). */
+export function lerCsv(texto) {
+  const linhas = (texto ?? '').replace(/^\uFEFF/, '').split(/\r?\n/).filter((l) => l.trim());
+  const colunas = linhas.length ? campos(linhas[0]) : [];
+  return { colunas, linhas: linhas.slice(1).map((l) => Object.fromEntries(campos(l).map((v, i) => [colunas[i] ?? `c${i}`, v]))) };
+}
+
+export const COLUNAS = ['id', 'displayName', 'title', 'icon', 'path', 'execution'];
+const campo = (v) => (/[\s,"]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v);
+
+/**
+ * O manifesto refeito a partir dos agentes: as 6 colunas, na ordem do manifesto antigo (agente novo
+ * vai para o fim); `execution` vem do agente, depois do manifesto antigo, depois `inline`.
+ */
+export function montarCsv(agentes, antigo) {
+  const velho = lerCsv(antigo);
+  const ordem = (a) => { const i = velho.linhas.findIndex((l) => l.id === a.id); return i < 0 ? Infinity : i; };
+  const emOrdem = [...agentes].sort((a, b) => ordem(a) - ordem(b));
+  const eol = antigo ? eolDe(antigo) : '\n';
+  const linha = (a) => {
+    const antes = velho.linhas.find((l) => l.id === a.id) ?? {};
+    const d = a.dados;
+    return [a.id, d.name ?? '', d.title ?? antes.title ?? '', d.icon ?? antes.icon ?? '', `./agents/${a.id}.agent.md`, d.execution ?? antes.execution ?? 'inline'].map((v) => campo(String(v))).join(',');
+  };
+  return [COLUNAS.join(','), ...emOrdem.map(linha), ''].join(eol);
+}