@aksp/opencrew 1.7.1 → 1.9.0

package/templates/_opencrew/core/scripts/entrega/destino.mjs

@@ -0,0 +1,98 @@
+// O destino da cópia: a pasta do projeto que o usuário escolheu para guardar a entrega. Vem de
+// `--lembrar-destino`, de `--destino` ou de `entrega.destino` no `crew.yaml`, nessa ordem, e uma
+// função só valida os três. Este módulo só lê.
+// Spec: fase-u3a2-entrega-no-projeto.md, §3 e regra 13 (repositório do OpenCrew).
+import { existsSync, promises as fs, statSync } from 'node:fs';
+import path from 'node:path';
+import { lugarReal } from '../comum.mjs';
+import { limpar } from './argumentos.mjs';
+
+export const MSG = {
+  recusado: (valor) => `Não copiei: o destino precisa ser uma pasta dentro do projeto, fora de \`_opencrew/\`, \`crews/\`, \`skills/\`, \`.git/\` e \`node_modules/\`. Recebi: ${limpar(valor)}.`,
+  semDestino: 'Cópia: nenhuma pasta escolhida para esta crew.',
+};
+
+const PROIBIDAS = new Set(['_opencrew', 'crews', 'skills', '.git', 'node_modules']);
+const NAO = /^(?:nao|não|no)$/i;
+// Absoluto: começa por `/`, `\` ou letra de unidade. Lista ou mapa do YAML não é caminho.
+const NAO_E_CAMINHO = /^(?:[\\/]|[A-Za-z]:|[[{]|-(?:\s|$))/;
+
+/** Relativo à raiz, com `/`; null quando sai do projeto, é a raiz ou cai numa pasta reservada. */
+function dentro(raiz, alvo) {
+  const rel = path.relative(raiz, alvo);
+  if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
+  const partes = rel.split(path.sep);
+  return PROIBIDAS.has(partes[0].toLowerCase()) ? null : partes.join('/');
+}
+
+/** O trecho do caminho que já existe é uma pasta? Um arquivo no caminho impede a cópia. */
+function semArquivoNoCaminho(abs) {
+  let existente = abs;
+  while (!existsSync(existente)) existente = path.dirname(existente);
+  return statSync(existente).isDirectory();
+}
+
+/**
+ * Valida um destino (regra 13), venha de onde vier.
+ * @returns {{ tipo: 'nao' } | { tipo: 'recusado', valor: string } | { tipo: 'pasta', rel: string, abs: string }}
+ *   `nao`: o usuário não quer cópia · `rel`: relativo ao projeto, com `/`
+ */
+export function validarDestino(raiz, valor) {
+  const texto = String(valor ?? '').trim();
+  if (NAO.test(texto)) return { tipo: 'nao' };
+  const recusado = { tipo: 'recusado', valor: texto };
+  if (!texto || NAO_E_CAMINHO.test(texto)) return recusado;
+  // \ vale como separador em qualquer sistema: o usuário digita Pasta\Sub também fora do Windows.
+  const abs = path.resolve(raiz, texto.replace(/\\/g, '/'));
+  const rel = dentro(raiz, abs);
+  // Pelo lugar real também: um atalho dentro do projeto pode levar para fora, ou para `crews/`.
+  if (!rel || !dentro(lugarReal(raiz), lugarReal(abs)) || !semArquivoNoCaminho(abs)) return recusado;
+  return { tipo: 'pasta', rel, abs };
+}
+
+const semFim = (linha) => linha.replace(/\r?\n$/, '');
+const recuoDe = (linha) => linha.match(/^[ \t]*/)[0];
+
+/**
+ * O bloco `entrega:` de um `crew.yaml` já separado em linhas: onde começa e acaba, o recuo dos
+ * filhos e a linha de `destino:` (um nível abaixo; -1 quando não há). Sem o bloco: null.
+ */
+export function blocoDaEntrega(linhas) {
+  const limpas = linhas.map(semFim);
+  const inicio = limpas.findIndex((l) => /^entrega:\s*(?:#.*)?$/.test(l));
+  if (inicio < 0) return null;
+  let fim = inicio + 1;
+  while (fim < limpas.length && (!limpas[fim].trim() || /^[ \t]/.test(limpas[fim]))) fim += 1;
+  const filhos = limpas.slice(inicio + 1, fim).filter((l) => l.trim());
+  const recuo = filhos.length ? recuoDe(filhos[0]) : '  ';
+  const destino = limpas.findIndex((l, i) => i > inicio && i < fim && recuoDe(l) === recuo && /^destino:/.test(l.trim()));
+  return { inicio, fim, recuo, destino };
+}
+
+/** O valor de uma linha `chave: valor`: sem as aspas e sem o comentário do fim da linha. */
+function valorDaLinha(linha) {
+  const resto = linha.slice(linha.indexOf(':') + 1).trim();
+  const comAspas = resto.match(/^(["'])(.*?)\1\s*(?:#.*)?$/);
+  return comAspas ? comAspas[2] : resto.replace(/(?:^|\s+)#.*$/, '').trim();
+}
+
+/** `entrega.destino` como está escrito no texto de um `crew.yaml`; null quando não há. Uma lista volta como o primeiro item dela (`- a`), que nunca é um destino válido. */
+export function destinoDoTexto(texto) {
+  const linhas = texto.replace(/^\uFEFF/, '').split(/\r?\n/);
+  const bloco = blocoDaEntrega(linhas);
+  if (!bloco || bloco.destino < 0) return null;
+  const valor = valorDaLinha(linhas[bloco.destino]);
+  if (valor) return valor;
+  const seguinte = (linhas[bloco.destino + 1] ?? '').trim();
+  return seguinte.startsWith('-') ? seguinte : null;
+}
+
+/**
+ * O destino desta chamada: `--lembrar-destino` vence `--destino`, que vence o `crew.yaml`.
+ * @returns {Promise<object>} o que `validarDestino` devolve, ou `{ tipo: 'nenhum' }` (ninguém escolheu)
+ */
+export async function escolherDestino(raiz, crew, args) {
+  const doYaml = async () => destinoDoTexto(await fs.readFile(path.join(crew, 'crew.yaml'), 'utf8'));
+  const valor = args.lembrarDestino ?? args.destino ?? (await doYaml());
+  return valor == null ? { tipo: 'nenhum' } : validarDestino(raiz, valor);
+}

package/templates/_opencrew/core/scripts/entrega/fora.mjs

@@ -0,0 +1,50 @@
+// Blocos de rótulo do arquivo de origem que não chegam à entrega: os de serviço (notas, checklist,
+// FORMAT) e, nos formatos lidos pelo leitor de peças, os que não são a peça do formato (os SLIDES
+// de um carrossel, por exemplo). A entrega não muda: o LEIA-ME só passa a dizer o que ficou fora.
+// Specs: fase-u3a1-pasta-de-entrega.md, §4 e §6, ajuste da execução real, e
+// fase-u3a2-entrega-no-projeto.md, §6: o aviso do LEIA-ME cita o arquivo de origem (repositório do OpenCrew).
+import { semFrontmatter } from '../verificar/leitura.mjs';
+import { ROTULOS } from '../verificar/pecas.mjs';
+import { lerTrechos, marcar } from '../verificar/secoes.mjs';
+import { PRINCIPAL } from './leitor.mjs';
+import { ehServico, secoesDeRotulo, semComentarios } from './texto.mjs';
+
+export const MSG = {
+  fora: (blocos, arquivo) => `Ficou fora do texto para colar: ${blocos.join(', ')}. Veja no arquivo de origem, \`${arquivo}\`.`,
+  foraNaTela: (arquivo, blocos) => `${arquivo}: ficou fora do texto para colar: ${blocos.join(', ')}. Veja no arquivo de origem.`,
+};
+
+const tabelaDe = (formato) => (formato === 'twitter-thread' ? 'twitter-post' : formato);
+
+/** O bloco deste rótulo chega à entrega? `formato`: o do leitor de peças, ou null (só o de serviço sai). */
+function entra(rotulo, formato) {
+  if (ehServico(rotulo)) return false;
+  if (!formato) return true;
+  const papel = ROTULOS[tabelaDe(formato)]?.[rotulo];
+  return papel === PRINCIPAL[formato] || papel === 'parte' || rotulo === 'HASHTAGS';
+}
+
+/** As seções de rótulo como o leitor de peças as vê: cada uma vai até o próximo rótulo ou cabeçalho de peça. */
+function secoesDoLeitor(corpo, formato) {
+  const trechos = lerTrechos(marcar(corpo), tabelaDe(formato)).filter((t) => t.rotulo);
+  return trechos.map((t) => ({ rotulo: t.rotulo, texto: t.linhas.join('\n').trim() }));
+}
+
+/**
+ * Rótulos dos blocos com texto que ficam fora da entrega, cada um uma vez, na ordem do arquivo.
+ * @param {string} texto o arquivo de origem, sem BOM e com LF
+ * @param {string|null} [formato] formato lido pelo leitor de peças (`instagram-feed`,
+ *   `linkedin-post`, `twitter-post`, `twitter-thread`); null nos outros, em que só o bloco de
+ *   serviço fica fora
+ * @returns {string[]}
+ */
+export function blocosFora(texto, formato = null) {
+  const corpo = semComentarios(semFrontmatter(texto));
+  const secoes = formato ? secoesDoLeitor(corpo, formato) : secoesDeRotulo(corpo);
+  return [...new Set(secoes.filter((s) => s.rotulo && s.texto && !entra(s.rotulo, formato)).map((s) => s.rotulo))];
+}
+
+/** O aviso de um arquivo: `{ pasta, texto, tela }`, ou nenhum quando nada ficou fora. */
+export function avisoDeFora(item, blocos) {
+  return blocos.length ? [{ pasta: item.canal, texto: MSG.fora(blocos, item.rel), tela: MSG.foraNaTela(item.rel, blocos) }] : [];
+}

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

@@ -0,0 +1,83 @@
+// Gravação da entrega: montada em `entrega.tmp/`, ao lado, e trocada no fim. Nada pela metade:
+// em qualquer falha a entrega anterior fica como estava e não sobra pasta temporária. O script só
+// apaga a própria `entrega/` e os temporários que ele mesmo criou.
+// Spec: fase-u3a1-pasta-de-entrega.md, regras 12 e 15 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+const apagar = (pasta) => fs.rm(pasta, { recursive: true, force: true, maxRetries: 3 });
+
+/** 'pasta', 'arquivo' ou null (não existe). */
+async function tipoDe(caminho) {
+  try {
+    return (await fs.stat(caminho)).isDirectory() ? 'pasta' : 'arquivo';
+  } catch {
+    return null;
+  }
+}
+
+/** Temporário que sobrou de uma chamada interrompida: a pasta é do script; arquivo com o mesmo nome não é. */
+async function limparSobras({ entrega, tmp, antiga }) {
+  if ((await tipoDe(antiga)) === 'pasta') {
+    if (await tipoDe(entrega)) await apagar(antiga);
+    else await fs.rename(antiga, entrega); // a troca anterior parou no meio: a entrega volta
+  }
+  if ((await tipoDe(tmp)) === 'pasta') await apagar(tmp);
+}
+
+/** Grava um arquivo da entrega na pasta temporária: o texto gerado, ou os mesmos bytes da origem. */
+async function gravarArquivo(destino, a) {
+  await fs.mkdir(path.dirname(destino), { recursive: true });
+  if (a.texto != null) await fs.writeFile(destino, a.texto, 'utf8');
+  else await fs.copyFile(a.de, destino);
+}
+
+/** Põe a pasta nova no lugar da anterior; se a nova não entra, a anterior volta. */
+async function trocar({ entrega, tmp, antiga }, passo) {
+  const anterior = await tipoDe(entrega);
+  passo(entrega);
+  if (anterior === 'arquivo') throw new Error('entrega não é uma pasta');
+  if (anterior) await fs.rename(entrega, antiga);
+  try {
+    await fs.rename(tmp, entrega);
+  } catch (erro) {
+    if (anterior) await fs.rename(antiga, entrega);
+    throw erro;
+  }
+  passo(antiga);
+  if (anterior) await apagar(antiga);
+}
+
+/**
+ * Refaz `entrega/` do zero e grava, ao lado, o relatório da verificação.
+ * @param {string} execucao pasta da execução (`crews/<crew>/output/<run>/`), absoluta
+ * @param {object[]} arquivos `{ pasta, nome, texto | de }`
+ * @param {{ leiame: string, relatorio: string }} textos
+ * @returns {Promise<string|null>} null quando gravou tudo; senão, o caminho que não foi gravado
+ */
+export async function gravarEntrega(execucao, arquivos, { leiame, relatorio }) {
+  const pastas = { entrega: path.join(execucao, 'entrega'), tmp: path.join(execucao, 'entrega.tmp'), antiga: path.join(execucao, 'entrega.antiga.tmp') };
+  let alvo = pastas.tmp;
+  let criei = false;
+  const passo = (caminho) => { alvo = caminho; };
+  try {
+    await limparSobras(pastas);
+    await fs.mkdir(pastas.tmp);
+    criei = true;
+    for (const a of arquivos) {
+      passo(path.join(pastas.tmp, a.pasta, a.nome));
+      await gravarArquivo(alvo, a);
+    }
+    passo(path.join(pastas.tmp, 'LEIA-ME.md'));
+    await fs.writeFile(alvo, leiame, 'utf8');
+    await trocar(pastas, passo);
+    criei = false;
+    passo(path.join(execucao, 'verificacao-entrega.md'));
+    await fs.writeFile(alvo, relatorio, 'utf8');
+    return null;
+  } catch {
+    if (criei) await apagar(pastas.tmp).catch(() => {});
+    // O arquivo que falhou dentro da pasta temporária é citado pelo lugar em que ficaria.
+    return alvo.startsWith(pastas.tmp + path.sep) ? path.join(pastas.entrega, alvo.slice(pastas.tmp.length + 1)) : alvo;
+  }
+}

package/templates/_opencrew/core/scripts/entrega/guardar.mjs

@@ -0,0 +1,60 @@
+// Guardar a entrega no projeto: decide o que está pronto para ser copiado, chama a cópia e diz,
+// em uma ou duas linhas do resumo, o que aconteceu. Canal com pendência não aceita fica de fora,
+// e o HTML editável dele também. Depois da cópia, guarda o retrato do que foi copiado (`copia.json`).
+// Spec: fase-u3a2-entrega-no-projeto.md, regras 13 a 15 e §6 (repositório do OpenCrew).
+import { relativoAoProjeto } from '../comum.mjs';
+import { EDITAVEIS } from './canais.mjs';
+import { retratoDe } from './comparar.mjs';
+import { copiar } from './copia.mjs';
+import { MSG as DESTINO } from './destino.mjs';
+import { montarLeiame } from './leiame.mjs';
+import { gravarRetratos, lerRetratos } from './retrato.mjs';
+
+export const MSG = {
+  falhaDeEscrita: (arquivo) => `Não consegui gravar ${arquivo}. Feche o arquivo, ou espere a sincronização da pasta, e rode de novo.`,
+  criei: (destino) => `Criei a pasta ${destino}.`,
+  nova: (pasta) => `Cópia: ${pasta}`,
+  igual: (pasta) => `Cópia: ${pasta} — já está atualizada.`,
+  completada: (pasta, n) => `Cópia: ${pasta} — completei com ${n} ${n === 1 ? 'arquivo novo' : 'arquivos novos'}.`,
+  reentrega: (pasta) => `Cópia: ${pasta} — guardei aqui porque a entrega mudou. Os arquivos da anterior ficaram como estavam; só o LEIA-ME dela ganhou um aviso.`,
+  nada: 'Cópia: nada foi copiado, porque nenhum canal está pronto.',
+};
+
+/** A pasta cuja situação decide se o arquivo é copiado: a do canal (o editável segue o canal dele). */
+const canalDe = (a) => (a.pasta === EDITAVEIS ? a.doCanal : a.pasta);
+
+/** Pasta criada nesta chamada: o retrato dela começa do zero. */
+const ehNova = (r) => r.tipo === 'nova' || r.tipo === 'reentrega';
+
+/** As linhas do resumo para o que a cópia devolveu. */
+function linhasDe(r, destino) {
+  if (r.tipo === 'nova') return [...(r.criouDestino ? [MSG.criei(destino.rel)] : []), MSG.nova(r.pasta)];
+  return [MSG[r.tipo](r.pasta, r.novos)];
+}
+
+/**
+ * Copia para o destino o que está pronto e descreve o resultado.
+ * @param {string} raiz pasta do projeto · @param {object} destino o que `escolherDestino` devolveu
+ * @param {object} dados os dados da entrega (os do LEIA-ME)
+ * @param {string} execucao a pasta da execução, absoluta: é nela que fica o retrato da cópia
+ * @returns {Promise<{ linhas: string[], pasta: string|null, falhou: boolean }>} `linhas`: as do
+ *   resumo · `pasta`: a pasta da cópia, relativa ao projeto, quando há uma · `falhou`: destino
+ *   recusado ou gravação que falhou (o final é ENTREGA:INCOMPLETA)
+ */
+export async function guardar(raiz, destino, dados, execucao) {
+  if (destino.tipo === 'nao') return { linhas: [], pasta: null, falhou: false };
+  if (destino.tipo === 'nenhum') return { linhas: [DESTINO.semDestino], pasta: null, falhou: false };
+  if (destino.tipo === 'recusado') return { linhas: [DESTINO.recusado(destino.valor)], pasta: null, falhou: true };
+  const pronto = (a) => !dados.pendencias.has(canalDe(a));
+  const arquivos = dados.arquivos.filter(pronto);
+  if (!arquivos.length) return { linhas: [MSG.nada], pasta: null, falhou: false };
+  const ignorar = new Set(dados.arquivos.filter((a) => !pronto(a)).map((a) => `${a.pasta}/${a.nome}`));
+  const leiame = (n) => montarLeiame({ ...dados, arquivos, ehCopia: true, reentrega: n });
+  const retratos = await lerRetratos(execucao);
+  const r = await copiar({ destino, run: dados.run, arquivos, ignorar, leiame, retratos });
+  if (r.tipo === 'falha') return { linhas: [MSG.falhaDeEscrita(relativoAoProjeto(raiz, r.arquivo))], pasta: null, falhou: true };
+  // O retrato da pasta: o que já estava nele e o que esta entrega tem (copiado agora ou igual ao que foi).
+  const semRetrato = await gravarRetratos(execucao, { ...retratos, [r.pasta]: { ...(ehNova(r) ? {} : retratos[r.pasta]), ...(await retratoDe(arquivos)) } });
+  const falha = semRetrato ? [MSG.falhaDeEscrita(relativoAoProjeto(raiz, semRetrato))] : [];
+  return { linhas: [...linhasDe(r, destino), ...falha], pasta: r.pasta, falhou: falha.length > 0 };
+}

package/templates/_opencrew/core/scripts/entrega/leiame.mjs

@@ -0,0 +1,125 @@
+// O LEIA-ME.md da entrega e o da cópia: títulos fixos, na ordem da spec; seção sem conteúdo não
+// aparece. Arquivo da entrega é citado com caminho relativo à pasta do LEIA-ME; o de origem,
+// relativo ao projeto. Sem hora: as mesmas entradas geram os mesmos bytes. PT-BR fixo.
+// Specs: fase-u3a1-pasta-de-entrega.md, §4 e §6, e fase-u3a2-entrega-no-projeto.md, §4 e §6
+// (ressalvas, a cópia e "Sobre esta pasta"), no repositório do OpenCrew.
+import { CANAIS, EDITAVEIS, OUTROS } from './canais.mjs';
+import { frasesDePendencia } from './pendencias.mjs';
+import { passosDe } from './passos.mjs';
+
+export const TEXTO = {
+  vaiPublicar: 'Esta crew publica este canal sozinha. Antes de postar à mão, confira se já saiu.',
+  pdf: 'Abra o arquivo que você quer no navegador ou no editor de texto e use Imprimir → Salvar como PDF.',
+  semCanal: 'sem canal de publicação; está aqui para você usar como quiser.',
+  sobre: 'Esta pasta é refeita a cada entrega e fica fora do git: o que você editar aqui se perde. Para guardar, copie a pasta para outro lugar do projeto.',
+  sobreComCopia: (pasta) => `Esta pasta é refeita a cada entrega e fica fora do git: o que você editar aqui se perde. A cópia para guardar está em \`${pasta}\`.`,
+  sobreDaCopia: (run) => `Esta é a cópia da entrega da execução ${run}. Ela não é refeita: pode editar e guardar. Se a entrega mudar, a versão nova vai para outra pasta, ao lado desta.`,
+  comRessalva: 'Entregue com ressalva:',
+  pronto: 'Pronto',
+  prontoComRessalva: 'Pronto, com ressalva',
+  naoPronto: 'Não está pronto',
+};
+
+const lista = (linhas) => linhas.map((l) => `- ${l}`).join('\n');
+const bloco = (titulo, linhas) => (linhas.length ? [`${titulo}\n${lista(linhas)}`] : []);
+const secao = (titulo, partes) => (partes.length ? [`## ${titulo}\n\n${partes.join('\n\n')}`] : []);
+
+/** A situação de um canal: uma só. Pendência não aceita vale sobre a ressalva. */
+export function situacaoDe(d, pasta) {
+  if (d.pendencias.has(pasta)) return TEXTO.naoPronto;
+  return d.ressalvas.has(pasta) ? TEXTO.prontoComRessalva : TEXTO.pronto;
+}
+
+/** Uma linha por arquivo entregue: o caminho na entrega, o título do bloco (se houver) e a origem. */
+function linhaDoArquivo(a) {
+  const titulo = a.titulo ? ` — ${a.titulo}` : '';
+  return `\`${a.pasta}/${a.nome}\`${titulo} — origem: \`${a.origem}\``;
+}
+
+/** Os avisos de uma pasta que o LEIA-ME mostra (o que só vai para a tela não tem `texto`). */
+const avisosDe = (d, pasta) => d.avisos.filter((a) => a.pasta === pasta && a.texto).map((a) => a.texto);
+
+/** A linha de uma ressalva; a de [PREENCHER] cita os arquivos entregues daquela origem que têm o trecho. */
+function linhaDaRessalva(d, r) {
+  const temOTrecho = (a) => a.origem === r.chave.arquivo && a.texto?.includes('[PREENCHER') && a.texto.includes(r.preencher);
+  const onde = r.preencher ? d.arquivos.filter(temOTrecho).map((a) => `\`${a.pasta}/${a.nome}\``) : [];
+  return `${r.linha}${onde.length ? ` — está em ${onde.join(', ')}` : ''}`;
+}
+
+/** `## Antes de usar`: as ressalvas, os alertas de tamanho e, por canal que não está pronto, o que falta. */
+function antesDeUsar(d) {
+  const ressalvas = [...d.ressalvas.values()].flat().map((r) => linhaDaRessalva(d, r));
+  const pastas = [...d.pastas, OUTROS].filter((p) => d.pendencias.has(p));
+  const frases = frasesDePendencia(pastas, d.pendencias);
+  const faltas = pastas.map((p, i) => `- ${frases[i]}\n${d.pendencias.get(p).map((l) => `  - ${l}`).join('\n')}`);
+  // Na cópia, o alerta de um arquivo que não foi copiado não aparece: ele cita um arquivo que não está lá.
+  const alertas = d.alertas.filter((a) => !d.ehCopia || !d.pendencias.has(a.pasta)).map((a) => `- ${a.texto}`);
+  return secao('Antes de usar', [...bloco(TEXTO.comRessalva, ressalvas), [...alertas, ...faltas].join('\n')].filter(Boolean));
+}
+
+/** `## {Canal}`: o aviso de publicação, a situação, os arquivos, as pendências, os avisos e os passos. */
+function secaoDoCanal(d, pasta) {
+  const pendencias = d.pendencias.get(pasta) ?? [];
+  const situacao = `Situação: ${situacaoDe(d, pasta)}`;
+  // Na cópia, o canal que não foi copiado traz só a situação e o que falta.
+  if (d.ehCopia && pendencias.length) return secao(CANAIS[pasta], [situacao, ...bloco('Pendências:', pendencias)]);
+  const arquivos = d.arquivos.filter((a) => a.pasta === pasta);
+  const passos = passosDe(pasta, arquivos, pendencias.length > 0, d.ressalvas.has(pasta)).map((p, i) => `${i + 1}. ${p}`);
+  return secao(CANAIS[pasta], [
+    ...(d.vaiPublicar.includes(pasta) ? [TEXTO.vaiPublicar] : []),
+    situacao,
+    ...bloco('Arquivos:', arquivos.map(linhaDoArquivo)),
+    ...bloco('Pendências:', pendencias),
+    ...bloco('Atenção:', avisosDe(d, pasta)),
+    ...(passos.length ? [`Passos:\n${passos.join('\n')}`] : []),
+  ]);
+}
+
+/** `## Outros arquivos` e `## Editáveis`: cada arquivo com a origem; em `outros`, a linha diz por que está ali. */
+function secaoDaPasta(d, pasta, titulo) {
+  const fim = pasta === OUTROS ? ` — ${TEXTO.semCanal}` : '';
+  const arquivos = d.arquivos.filter((a) => a.pasta === pasta).map((a) => `${linhaDoArquivo(a)}${fim}`);
+  const pendencias = d.pendencias.get(pasta) ?? [];
+  return secao(titulo, [
+    ...(arquivos.length ? [lista(arquivos)] : []),
+    ...bloco('Pendências:', pendencias),
+    ...(d.ehCopia && pendencias.length ? [] : bloco('Atenção:', avisosDe(d, pasta))),
+  ]);
+}
+
+/** `## Sobre esta pasta`: o que é a pasta da entrega (com a cópia, onde ela está) ou o que é a cópia. */
+function sobre(d) {
+  if (d.ehCopia) return TEXTO.sobreDaCopia(d.run);
+  return d.copiaEm ? TEXTO.sobreComCopia(d.copiaEm) : TEXTO.sobre;
+}
+
+/**
+ * @param {object} d
+ * @param {string} d.crew nome da crew · @param {string} d.run id da execução
+ * @param {string[]} d.pastas os canais presentes, na ordem das seções
+ * @param {object[]} d.arquivos `{ pasta, nome, tipo, origem, titulo, numerado }` — no LEIA-ME da
+ *   cópia, só os que foram copiados
+ * @param {object[]} d.avisos `{ pasta, texto, tela }` (`tela`: como o aviso sai no resumo da tela)
+ * @param {Map<string, string[]>} d.pendencias por pasta, as não aceitas
+ * @param {Map<string, object[]>} d.ressalvas por pasta, as aceitas: `{ linha, chave, preencher }`
+ * @param {object[]} d.alertas regra 34: `{ pasta, texto }`
+ * @param {string[]} d.naoConferido · @param {string[]} d.vaiPublicar canais que a crew publica
+ * @param {string|null} [d.copiaEm] a pasta da cópia, relativa ao projeto, quando ela foi feita
+ * @param {boolean} [d.ehCopia] é o LEIA-ME da cópia: todo arquivo citado existe nela
+ * @param {number} [d.reentrega] na cópia, o número da pasta: de 2 em diante, o título diz `(reentrega N)`
+ * @returns {string} o LEIA-ME, em UTF-8 sem BOM e com LF
+ */
+export function montarLeiame(d) {
+  const temMd = d.arquivos.some((a) => a.nome.toLowerCase().endsWith('.md'));
+  const partes = [
+    `# Entrega — ${d.crew} — ${d.run}${d.reentrega > 1 ? ` (reentrega ${d.reentrega})` : ''}`,
+    ...antesDeUsar(d),
+    ...d.pastas.flatMap((pasta) => secaoDoCanal(d, pasta)),
+    ...secaoDaPasta(d, OUTROS, 'Outros arquivos'),
+    ...secaoDaPasta(d, EDITAVEIS, 'Editáveis'),
+    ...secao('O que não foi conferido', [lista(d.naoConferido)]),
+    ...(temMd ? secao('Para ter um PDF', [TEXTO.pdf]) : []),
+    ...secao('Sobre esta pasta', [sobre(d)]),
+  ];
+  return `${partes.join('\n\n')}\n`;
+}

package/templates/_opencrew/core/scripts/entrega/leitor.mjs

@@ -0,0 +1,133 @@
+// Peças que vêm do leitor do verificador (`lerPecas`): legenda, post e tweet, cada um com as
+// suas hashtags no fim — e o primeiro comentário do LinkedIn, que sai do texto do post.
+// Spec: fase-u3a1-pasta-de-entrega.md, §4 e regra 4 (repositório do OpenCrew). A legenda sem
+// marcador (o arquivo que é só o texto) é da fase-u3a2-entrega-no-projeto.md, §4.
+import { semAcento } from '../verificar/leitura.mjs';
+import { contarSlides, lerPecas, listarHashtags } from '../verificar/pecas.mjs';
+import { lerTrechos, marcar, rotuloDe } from '../verificar/secoes.mjs';
+import { paraColar } from './texto.mjs';
+
+/** Peça principal de cada formato: sem ela, o arquivo vai inteiro. */
+export const PRINCIPAL = { 'instagram-feed': 'legenda', 'linkedin-post': 'post', 'twitter-post': 'tweet', 'twitter-thread': 'tweet' };
+const TITULO = /^(#{1,6})\s+(.*)$/s;
+const COMENTARIO = /(?<![\p{L}\p{N}])(?:comentarios?|comments?)(?![\p{L}\p{N}])/u;
+const marca = (n) => `⟦comentario:${n}⟧`;
+const MARCA = /^⟦comentario:(\d+)⟧$/;
+
+/**
+ * Tira do corpo as seções de comentário (cabeçalho com "comentário" ou "comment", até o próximo
+ * cabeçalho do mesmo nível ou acima, ou até um rótulo). No lugar de cada uma fica uma linha de
+ * marca: ela cai dentro do texto do post que vem antes.
+ * @returns {{ corpo: string, comentarios: string[] }}
+ */
+function tirarComentarios(corpo) {
+  const linhas = [];
+  const comentarios = [];
+  let nivel = 0; // nível do cabeçalho de comentário aberto; 0 = nenhum
+  for (const linha of corpo.split('\n')) {
+    const h = linha.match(TITULO);
+    if (nivel && (rotuloDe(linha) || (h && h[1].length <= nivel))) nivel = 0;
+    if (!nivel && h && COMENTARIO.test(semAcento(h[2]))) {
+      nivel = h[1].length;
+      linhas.push(marca(comentarios.push([]) - 1));
+    } else if (nivel) comentarios.at(-1).push(linha);
+    else linhas.push(linha);
+  }
+  return { corpo: linhas.join('\n'), comentarios: comentarios.map((c) => c.join('\n')) };
+}
+
+/** Texto da peça sem as linhas de marca, e os números dos comentários que estavam nele. */
+function separarMarcas(texto) {
+  const numeros = [];
+  const linhas = texto.split('\n').filter((linha) => {
+    const m = linha.trim().match(MARCA);
+    if (m) numeros.push(Number(m[1]));
+    return !m;
+  });
+  return { texto: linhas.join('\n'), numeros };
+}
+
+/** Cabeçalhos do corpo, na ordem: `[{ titulo, pai }]` (`pai`: o cabeçalho logo acima, ou null). */
+function cabecalhos(corpo) {
+  const lista = [];
+  let pilha = [];
+  for (const linha of corpo.split('\n')) {
+    const h = linha.match(TITULO);
+    if (!h) continue;
+    pilha = pilha.filter((c) => c.nivel < h[1].length);
+    lista.push({ titulo: h[2].trim(), pai: pilha.at(-1)?.titulo ?? null });
+    pilha.push({ nivel: h[1].length, titulo: h[2].trim() });
+  }
+  return lista;
+}
+
+/** Título do bloco de cada peça de cabeçalho: o cabeçalho logo acima do dela, quando houver. */
+function titulosDeBloco(corpo, pecas) {
+  const lista = cabecalhos(corpo);
+  let cursor = 0;
+  return pecas.map((p) => {
+    const i = p.origem === 'cabecalho' ? lista.findIndex((c, n) => n >= cursor && c.titulo === p.cabecalho) : -1;
+    if (i < 0) return null;
+    cursor = p.porParagrafo ? i : i + 1;
+    return lista[i].pai;
+  });
+}
+
+/** Hashtags da seção própria (rótulo ou cabeçalho) da legenda ou do post, sem as que já estão no texto. */
+function hashtagsDaPeca(pecas, p) {
+  const h = pecas.find((x) => x.tipo === 'hashtags' && x.de === p.tipo && x.ordem === p.ordem && x.formato === p.formato);
+  return h ? listarHashtags(h.texto).slice(listarHashtags(p.texto).length) : [];
+}
+
+/** Hashtags das seções `=== HASHTAGS ===` e de cabeçalho "Hashtags" de um arquivo de tweets. */
+export function hashtagsSoltas(corpo, tabela = 'twitter-post') {
+  const trechos = lerTrechos(marcar(corpo), tabela).filter((t) => t.rotulo === 'HASHTAGS' || t.tipos?.[0] === 'hashtags');
+  return trechos.flatMap((t) => listarHashtags(t.linhas.join('\n')));
+}
+
+const comHashtags = (texto, hashtags) => paraColar(hashtags.length ? `${texto}\n\n${hashtags.join(' ')}` : texto);
+
+/** Comentário de cada post: o que caiu no texto dele; os que sobraram vão, na ordem, para os posts sem comentário. */
+function distribuir(marcas, comentarios) {
+  const usados = new Set(marcas.flat());
+  const sobras = comentarios.map((_, n) => n).filter((n) => !usados.has(n));
+  return marcas.map((numeros) => (numeros.length ? numeros : sobras.splice(0, 1)).map((n) => comentarios[n]).join('\n\n'));
+}
+
+/**
+ * Arquivo de `instagram-feed` que é só o texto (sem rótulo, sem cabeçalho e sem linha "Slide N"): o
+ * corpo inteiro é a legenda, como o leitor do verificador já faz com o post e com o tweet. A
+ * unidade sai com `inteiro: true`, para o aviso.
+ */
+function legendaInteira(corpo) {
+  const soTexto = corpo.trim() && !contarSlides(corpo) && !marcar(corpo).some((m) => m.rotulo || m.nivel);
+  if (!soTexto) return [];
+  return [{ tipo: 'legenda', titulo: null, ordem: 1, total: 1, inteiro: true, partes: [{ nome: 'legenda', sufixo: '', ext: 'txt', tipo: 'legenda', texto: paraColar(corpo) }] }];
+}
+
+/**
+ * Lê as peças do formato num corpo já sem frontmatter e sem blocos de serviço.
+ * @returns {{ unidades: object[], temSlides: boolean, outros: string[] }} `unidades`: uma por
+ *   legenda, post ou tweet, `{ tipo, titulo, ordem, total, partes: [{ nome, sufixo, ext, tipo, texto }] }`
+ *   · `outros`: cabeçalhos das seções de outro canal, que não são separadas
+ */
+export function pecasDoLeitor(corpoOriginal, formato) {
+  const tabela = formato === 'twitter-thread' ? 'twitter-post' : formato;
+  const tipo = PRINCIPAL[formato];
+  const { corpo, comentarios } = tipo === 'post' ? tirarComentarios(corpoOriginal) : { corpo: corpoOriginal, comentarios: [] };
+  const pecas = lerPecas(corpo, tabela);
+  const principais = pecas.filter((p) => p.formato === tabela && p.tipo === tipo);
+  const limpas = principais.map((p) => separarMarcas(p.texto));
+  const doPost = distribuir(limpas.map((l) => l.numeros), comentarios);
+  const titulos = titulosDeBloco(corpo, principais);
+  const soltas = tipo === 'tweet' ? hashtagsSoltas(corpo) : [];
+  const unidades = principais.map((p, i) => {
+    const hashtags = tipo === 'tweet' ? (i === 0 ? soltas : []) : hashtagsDaPeca(pecas, p);
+    const partes = [{ nome: tipo, sufixo: '', ext: 'txt', tipo, texto: comHashtags(limpas[i].texto, hashtags) }];
+    if (doPost[i]?.trim()) partes.push({ nome: tipo, sufixo: '-comentario', ext: 'txt', tipo: 'comentario', texto: paraColar(doPost[i]) });
+    return { tipo, titulo: titulos[i], ordem: i + 1, total: principais.length, partes };
+  });
+  const outros = pecas.filter((p) => p.formato !== tabela && p.tipo !== 'hashtags' && p.cabecalho).map((p) => p.cabecalho);
+  const achadas = unidades.length || tipo !== 'legenda' ? unidades : legendaInteira(corpo);
+  return { unidades: achadas, temSlides: pecas.some((p) => p.formato === tabela && p.tipo === 'slides'), outros: [...new Set(outros)] };
+}

package/templates/_opencrew/core/scripts/entrega/lembrar.mjs

@@ -0,0 +1,65 @@
+// `--lembrar-destino`: grava `entrega.destino` no `crew.yaml`, sem mexer em nenhuma outra linha, e
+// deixa ao lado a cópia do arquivo anterior (`crew.yaml.bak`; se já existe, `.bak-<data-hora>`).
+// É o único arquivo fora da execução e do destino que a entrega escreve.
+// Spec: fase-u3a2-entrega-no-projeto.md, regra 16 (repositório do OpenCrew).
+import { constants, existsSync, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { blocoDaEntrega, destinoDoTexto, validarDestino } from './destino.mjs';
+
+const FIM = /\r?\n$/;
+const fimDe = (linha) => linha.match(FIM)?.[0] ?? '';
+const recuoDe = (linha) => linha.match(/^[ \t]*/)[0];
+
+/** O que já está gravado é o mesmo destino? (`Não` e `nao` são o mesmo "não"; `a\b` e `a/b`, a mesma pasta) */
+function jaGravado(raiz, texto, destino) {
+  const escrito = destinoDoTexto(texto);
+  if (escrito == null) return false;
+  const atual = validarDestino(raiz, escrito);
+  return atual.tipo === destino.tipo && atual.rel === destino.rel;
+}
+
+/** Troca a linha de `destino:` (e a lista que vinha embaixo dela, se havia) pela linha nova. */
+function trocar(linhas, bloco, linhaNova, eol) {
+  const i = bloco.destino;
+  let fim = i + 1;
+  while (fim < bloco.fim && linhas[fim].trim() && recuoDe(linhas[fim]).length > bloco.recuo.length) fim += 1;
+  linhas.splice(i, fim - i, `${linhaNova}${fimDe(linhas[i]) || eol}`);
+}
+
+/** O texto do `crew.yaml` com `entrega.destino: valor`; as outras linhas ficam como estavam, byte a byte. */
+export function comDestino(texto, valor) {
+  const eol = texto.includes('\r\n') ? '\r\n' : '\n';
+  const linhas = texto.split(/(?<=\n)/);
+  const bloco = blocoDaEntrega(linhas);
+  const escrito = valor === 'nao' ? 'nao' : JSON.stringify(valor);
+  if (bloco && bloco.destino >= 0) trocar(linhas, bloco, `${bloco.recuo}destino: ${escrito}`, eol);
+  else if (bloco) {
+    if (!fimDe(linhas[bloco.inicio])) linhas[bloco.inicio] += eol;
+    linhas.splice(bloco.inicio + 1, 0, `${bloco.recuo}destino: ${escrito}${eol}`);
+  } else {
+    if (linhas.length && !fimDe(linhas.at(-1))) linhas.push(eol);
+    linhas.push(`entrega:${eol}`, `  destino: ${escrito}${eol}`);
+  }
+  return linhas.join('');
+}
+
+const nomeDaCopia = (arquivo) => (existsSync(`${arquivo}.bak`) ? `${arquivo}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}` : `${arquivo}.bak`);
+
+/**
+ * Grava o destino no `crew.yaml`. Valor igual ao gravado: nada é regravado (nem cópia nova).
+ * @param {string} raiz pasta do projeto · @param {string} crew pasta da crew, absoluta
+ * @param {object} destino o que `validarDestino` devolveu: `nao` ou `pasta`
+ * @returns {Promise<string|null>} null quando está gravado; senão, o arquivo que não foi gravado
+ */
+export async function lembrarDestino(raiz, crew, destino) {
+  const arquivo = path.join(crew, 'crew.yaml');
+  try {
+    const antes = await fs.readFile(arquivo, 'utf8');
+    if (jaGravado(raiz, antes, destino)) return null;
+    await fs.copyFile(arquivo, nomeDaCopia(arquivo), constants.COPYFILE_EXCL);
+    await fs.writeFile(arquivo, comDestino(antes, destino.tipo === 'nao' ? 'nao' : destino.rel), 'utf8');
+    return null;
+  } catch {
+    return arquivo;
+  }
+}