@aksp/opencrew 1.10.0 → 1.11.0

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);
+}

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

@@ -0,0 +1,55 @@
+// A gravação do conserto: o que impede de gravar é visto antes de tocar em qualquer arquivo; cada
+// arquivo alterado ganha antes a cópia `.bak` (a que já existe fica).
+// Spec: fase-u4a-conserto-de-crews.md, regras 1 e 2 (repositório do OpenCrew).
+import { accessSync, constants, existsSync, writeFileSync } from 'node:fs';
+import { relativoAoProjeto } from '../comum.mjs';
+
+const MSG = {
+  naoUtf8: (arquivo) => `Não altero ${arquivo}: o arquivo não está em UTF-8. Salve-o em UTF-8 e rode de novo.`,
+  somenteLeitura: (arquivo) => `Não consigo gravar em ${arquivo} (arquivo protegido ou aberto em outro programa). Nada foi gravado.`,
+  parouNoMeio: (gravados, arquivo, motivo) => `A gravação parou em ${arquivo}: ${motivo}. Já gravados: ${gravados.join(', ') || 'nenhum'} (a cópia .bak de cada um tem o texto de antes).`,
+};
+
+const INVALIDO = String.fromCharCode(0xfffd); // o que sobra de um byte que não é UTF-8
+
+function podeGravar(arquivo) {
+  try {
+    accessSync(arquivo, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** O que impede a gravação, visto antes de tocar em qualquer arquivo: texto que não é UTF-8, arquivo protegido. */
+export function erroAntesDeGravar(raiz, mudancas) {
+  const rel = (m) => relativoAoProjeto(raiz, m.arquivo);
+  const estranho = mudancas.find((m) => m.antes?.includes(INVALIDO));
+  if (estranho) return MSG.naoUtf8(rel(estranho));
+  const fechado = mudancas.find((m) => m.antes !== null && !podeGravar(m.arquivo));
+  return fechado ? MSG.somenteLeitura(rel(fechado)) : null;
+}
+
+/**
+ * Grava as mudanças; antes de cada arquivo, a cópia `.bak` do que estava lá (se ainda não existe).
+ * @returns {string[]} as linhas do relatório, com os caminhos relativos ao projeto
+ */
+export function gravar(raiz, mudancas) {
+  const linhas = [];
+  const gravados = [];
+  for (const { arquivo, antes, depois } of mudancas) {
+    const rel = relativoAoProjeto(raiz, arquivo);
+    const copia = `${arquivo}.bak`;
+    const jaHavia = existsSync(copia);
+    try {
+      if (antes !== null && !jaHavia) writeFileSync(copia, antes, 'utf8');
+      writeFileSync(arquivo, depois, 'utf8');
+    } catch (falha) {
+      throw new Error(MSG.parouNoMeio(gravados, rel, falha?.code ?? falha?.message ?? falha), { cause: falha });
+    }
+    gravados.push(rel);
+    linhas.push(`Gravei: ${rel}`);
+    if (antes !== null) linhas.push(`Cópia: ${rel}.bak${jaHavia ? ' (mantive a cópia que já existia)' : ''}`);
+  }
+  return linhas;
+}

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

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Conserto de uma crew que já existe: mostra o que falta para as melhorias do runtime valerem nela
+// e, com --aplicar, grava um item por vez. Quem grava em `crews/` é este script, não a IA.
+// Uso (na pasta do projeto):
+//   node _opencrew/core/scripts/conserto.mjs --crew "crews/<crew>"                      só lê
+//   node _opencrew/core/scripts/conserto.mjs --crew "crews/<crew>" --aplicar "<item>"   grava
+// Itens de --aplicar: manifesto · nome:<agente>=<Nome Sobrenome> · formato:<passo>=<formato> ·
+//   fonte:<caminho>=<para que> · proibicao:<n>=<trecho> · proibicao:<n>=revisao-humana ·
+//   irreversivel:<passo> (ver --ajuda).
+// Só grava `crew.yaml`, `crew-party.csv`, `agents/*.agent.md`, `pipeline/steps/*.md` e
+// `_memory/memories.md` da crew, e a cópia `<arquivo>.bak` de cada um (a cópia que já existe
+// não é sobrescrita). Nunca apaga.
+// Última linha da saída: CONSERTO:OK (nada a consertar) · CONSERTO:PENDENTE (há achados) ·
+// CONSERTO:APLICADO (tudo o que foi pedido está gravado) · CONSERTO:ERRO (nada foi gravado).
+// Código de saída: 0, menos com CONSERTO:ERRO (1).
+// Spec: fase-u4a-conserto-de-crews.md (repositório do OpenCrew).
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { ehPrincipal, erroDeUso } from './comum.mjs';
+import { diagnosticar } from './conserto/achados.mjs';
+import { planejar } from './conserto/aplicar.mjs';
+import { AJUDA, lerArgs, lerItem, limpar } from './conserto/argumentos.mjs';
+import { lerCrew } from './conserto/crew.mjs';
+import { gravar } from './conserto/gravar.mjs';
+
+const MSG = {
+  estranho: (arg) => `Argumento desconhecido: ${limpar(arg)}. Veja as opções com --ajuda.`,
+  semYaml: (crew) => `A pasta ${limpar(crew)} não tem \`crew.yaml\`: não é uma crew.`,
+  itemDesconhecido: (item) => `Item desconhecido em --aplicar: ${limpar(item)}. Veja os itens com --ajuda.`,
+  emDia: (nome) => `A crew "${nome}" está em dia: não há o que consertar.`,
+  titulo: (nome, n) => `Conserto da crew "${nome}" — ${n} ${n === 1 ? 'achado' : 'achados'}`,
+  jaEstava: (item) => `Já estava assim: ${item}`,
+  falha: (motivo) => `Não consegui consertar: ${String(motivo).replace(/\s+/g, ' ').trim()}`,
+};
+
+/** O que está errado na chamada, antes de ler a crew; ou null. */
+function erroDaChamada(raiz, args) {
+  if (args.estranho !== undefined) return MSG.estranho(args.estranho);
+  const deUso = erroDeUso({ raiz, faltando: args.crew ? [] : ['--crew'], crew: args.crew });
+  if (deUso) return deUso;
+  if (!existsSync(path.resolve(raiz, args.crew, 'crew.yaml'))) return MSG.semYaml(args.crew);
+  const desconhecido = args.itens.find((i) => !lerItem(i));
+  return desconhecido === undefined ? null : MSG.itemDesconhecido(desconhecido);
+}
+
+/** As linhas do diagnóstico: um bloco por achado e a linha de situação. */
+function relatorio(crew) {
+  const achados = diagnosticar(crew);
+  if (!achados.length) return [MSG.emDia(crew.nome), 'CONSERTO:OK'];
+  const blocos = achados.flatMap(({ codigo, linhas: [titulo, ...resto] }) => ['', `[${codigo}] ${titulo}`, ...resto.map((l) => `  ${l}`)]);
+  return [MSG.titulo(crew.nome, achados.length), ...blocos, '', 'CONSERTO:PENDENTE'];
+}
+
+/** As linhas de um `--aplicar`: o que foi gravado, as cópias e a linha de situação. */
+function aplicar(raiz, crew, itens) {
+  const plano = planejar(crew, itens.map(lerItem));
+  if (plano.erro) return [plano.erro, 'CONSERTO:ERRO'];
+  return [...gravar(raiz, plano.mudancas), ...plano.iguais.map(MSG.jaEstava), 'CONSERTO:APLICADO'];
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps] `cwd` (a pasta do projeto) e `escrever`
+ * @returns {number} 0 = a crew foi lida (e, com --aplicar, gravada) · 1 = CONSERTO:ERRO
+ */
+export function main(argv, deps = {}) {
+  const { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = deps;
+  const args = lerArgs(argv);
+  if (args.ajuda) return AJUDA.forEach((l) => escrever(l)) ?? 0;
+  let linhas;
+  try {
+    const erro = erroDaChamada(cwd, args);
+    const crew = erro ? null : lerCrew(cwd, args.crew);
+    linhas = erro ? [erro, 'CONSERTO:ERRO'] : args.itens.length ? aplicar(cwd, crew, args.itens) : relatorio(crew);
+  } catch (falha) {
+    linhas = [MSG.falha(falha?.message ?? falha), 'CONSERTO:ERRO'];
+  }
+  linhas.forEach((l) => escrever(l));
+  return linhas.at(-1) === 'CONSERTO:ERRO' ? 1 : 0;
+}
+
+if (ehPrincipal(import.meta.url)) process.exitCode = main(process.argv.slice(2));