@aksp/opencrew 1.8.0 → 1.10.0

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

@@ -0,0 +1,104 @@
+// Comparação entre o que a entrega copiaria agora e a cópia que já está no destino: é ela que
+// decide se nada muda, se só há arquivos a acrescentar ou se a entrega vai para outra pasta.
+// Com o retrato do que foi copiado (`copia.json`, ver `retrato.mjs`), a comparação é com ele: o que o
+// usuário fez na cópia depois não conta. Sem retrato, é com os arquivos da pasta.
+// Este módulo só lê. Spec: fase-u3a2-entrega-no-projeto.md, regra 14 (repositório do OpenCrew).
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+// Em texto, CRLF e LF são o mesmo conteúdo (o editor ou a sincronização trocam); o resto, byte a byte.
+const DE_TEXTO = new Set(['.txt', '.md', '.html', '.htm', '.csv', '.json']);
+export const emLf = (texto) => texto.replace(/\r\n/g, '\n');
+
+/** Os bytes que um arquivo da entrega tem: os gerados (o Word), o texto gerado, ou os do arquivo de origem. */
+export const bytesDe = async (a) => a.bytes ?? (a.texto != null ? Buffer.from(a.texto, 'utf8') : fs.readFile(a.de));
+
+const ehTexto = (nome) => DE_TEXTO.has(path.extname(nome).toLowerCase());
+const mesmoConteudo = (nome, a, b) => a.equals(b) || (ehTexto(nome) && emLf(a.toString('utf8')) === emLf(b.toString('utf8')));
+
+/** Os arquivos sob uma pasta, com o prefixo dado e `/`; pasta que não existe: nenhum. */
+async function listar(pasta, prefixo) {
+  const entradas = await fs.readdir(pasta, { withFileTypes: true }).catch(() => []);
+  const achados = [];
+  for (const e of entradas) {
+    if (e.isDirectory()) achados.push(...(await listar(path.join(pasta, e.name), `${prefixo}${e.name}/`)));
+    else achados.push(`${prefixo}${e.name}`);
+  }
+  return achados;
+}
+
+const REENTREGA = '-reentrega-';
+
+/** 1 para `<run>`, N para `<run>-reentrega-N` (N ≥ 2), 0 para qualquer outro nome. */
+function numeroDe(nome, run) {
+  if (nome === run) return 1;
+  const n = nome.startsWith(`${run}${REENTREGA}`) ? nome.slice(run.length + REENTREGA.length) : '';
+  return /^[1-9]\d*$/.test(n) && Number(n) >= 2 ? Number(n) : 0;
+}
+
+/**
+ * As pastas desta execução no destino, da mais antiga para a mais nova: `<run>` é a 1 e
+ * `<run>-reentrega-N` é a N. Só pastas: arquivo com um desses nomes não conta.
+ * @returns {Promise<{ n: number, nome: string }[]>}
+ */
+export async function pastasDaExecucao(destino, run) {
+  const entradas = await fs.readdir(destino, { withFileTypes: true }).catch(() => []);
+  const pastas = entradas.filter((e) => e.isDirectory()).map((e) => ({ n: numeroDe(e.name, run), nome: e.name }));
+  return pastas.filter((p) => p.n).sort((a, b) => a.n - b.n);
+}
+
+const hashDe = (nome, bytes) => createHash('sha1').update(ehTexto(nome) ? emLf(bytes.toString('utf8')) : bytes).digest('hex');
+
+/** O retrato de uma lista de arquivos da entrega: `{ 'pasta/nome': hash }` (em texto, sem contar CRLF/LF). */
+export async function retratoDe(arquivos) {
+  const retrato = {};
+  for (const a of arquivos) retrato[`${a.pasta}/${a.nome}`] = hashDe(a.nome, await bytesDe(a));
+  return retrato;
+}
+
+/**
+ * A mesma pergunta de `oQueFalta`, respondida pelo retrato do que foi copiado para a pasta. O que
+ * o usuário editou, apagou ou acrescentou na cópia não é diferença. Arquivo novo cujo lugar já
+ * está ocupado só conta como copiado quando o conteúdo é o mesmo; senão, é diferença.
+ */
+async function contraORetrato(pasta, esperados, canais, ignorar, retrato) {
+  const saiu = (rel) => canais.has(rel.split('/')[0]) && !ignorar.has(rel) && !esperados.has(rel);
+  if (Object.keys(retrato).some(saiu)) return null;
+  const faltam = [];
+  for (const [rel, a] of esperados) {
+    const bytes = await bytesDe(a);
+    if (Object.hasOwn(retrato, rel)) {
+      if (retrato[rel] !== hashDe(rel, bytes)) return null;
+      continue;
+    }
+    const noDisco = await fs.readFile(path.join(pasta, rel)).catch(() => null);
+    if (noDisco == null) faltam.push(a);
+    else if (!mesmoConteudo(rel, noDisco, bytes)) return null;
+  }
+  return faltam;
+}
+
+/**
+ * Compara os arquivos que seriam copiados agora com uma pasta de cópia. Só as pastas de canal que
+ * seriam copiadas agora são olhadas: a raiz da cópia e as outras pastas ficam de fora.
+ * @param {string} pasta a cópia, absoluta · @param {object[]} arquivos `{ pasta, nome, texto | de }`
+ * @param {Set<string>} ignorar `pasta/nome` do que a entrega tem mas não copia agora
+ * @param {object|null} [retrato] o retrato do que foi copiado para esta pasta; null = comparar com os arquivos
+ * @returns {Promise<null | object[]>} null = diferente (arquivo que mudou, saiu ou está a mais);
+ *   senão, os arquivos que faltam na cópia (nenhum = igual)
+ */
+export async function oQueFalta(pasta, arquivos, ignorar, retrato = null) {
+  const esperados = new Map(arquivos.map((a) => [`${a.pasta}/${a.nome}`, a]));
+  if (retrato) return contraORetrato(pasta, esperados, new Set(arquivos.map((a) => a.pasta)), ignorar, retrato);
+  const faltam = new Map(esperados);
+  for (const canal of new Set(arquivos.map((a) => a.pasta))) {
+    for (const rel of await listar(path.join(pasta, canal), `${canal}/`)) {
+      if (ignorar.has(rel)) continue;
+      const a = esperados.get(rel);
+      if (!a || !mesmoConteudo(rel, await fs.readFile(path.join(pasta, rel)), await bytesDe(a))) return null;
+      faltam.delete(rel);
+    }
+  }
+  return [...faltam.values()];
+}

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

@@ -0,0 +1,138 @@
+// A cópia da entrega para a pasta do projeto que o usuário escolheu: uma pasta por execução
+// (`<destino>/<run_id>/`). Nada é sobrescrito, menos o `LEIA-ME.md` da cópia, que é do script.
+// Pasta nova é montada em `<pasta>.tmp/`, ao lado, e renomeada no fim: nada fica pela metade.
+// O script só apaga o temporário que ele mesmo criou. O que o usuário edita na cópia fica: a
+// entrega seguinte é comparada com o retrato do que foi copiado (`retrato.mjs`), não com a pasta.
+// Spec: fase-u3a2-entrega-no-projeto.md, regras 14 e 15 (repositório do OpenCrew).
+import { constants, existsSync, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { emLf, oQueFalta, pastasDaExecucao } from './comparar.mjs';
+
+export const AVISO = (pasta) => `Há uma entrega mais nova desta execução em \`${pasta}\`.`;
+const AVISO_ANTERIOR = /^Há uma entrega mais nova desta execução em `[^`\n]*`\.\r?\n\r?\n/;
+const LEIAME = 'LEIA-ME.md';
+const apagar = (pasta) => fs.rm(pasta, { recursive: true, force: true, maxRetries: 3 });
+const ehPasta = async (p) => fs.stat(p).then((s) => s.isDirectory(), () => false);
+
+/** Grava um arquivo que ainda não existe ali: se existir, falha (nunca por cima). */
+async function gravarNovo(alvo, a) {
+  await fs.mkdir(path.dirname(alvo), { recursive: true });
+  if ((a.bytes ?? a.texto) != null) await fs.writeFile(alvo, a.bytes ?? a.texto, { encoding: 'utf8', flag: 'wx' });
+  else await fs.copyFile(a.de, alvo, constants.COPYFILE_EXCL);
+}
+
+/** Monta a pasta nova no temporário e a põe no lugar; em falha, o temporário some. */
+async function montar(pasta, arquivos, leiame, em) {
+  const tmp = `${pasta}.tmp`;
+  if (await ehPasta(tmp)) await apagar(tmp); // sobra de uma chamada interrompida
+  await fs.mkdir(tmp);
+  try {
+    for (const a of arquivos) {
+      em.alvo = path.join(pasta, a.pasta, a.nome);
+      await gravarNovo(path.join(tmp, a.pasta, a.nome), a);
+    }
+    em.alvo = path.join(pasta, LEIAME);
+    await fs.writeFile(path.join(tmp, LEIAME), leiame, 'utf8');
+    em.alvo = pasta;
+    await fs.rename(tmp, pasta);
+  } catch (erro) {
+    await apagar(tmp).catch(() => {});
+    throw erro;
+  }
+}
+
+/** A pasta mais alta do caminho que ainda não existe (é a que o script cria); null quando todas existem. */
+function primeiraQueFalta(pasta) {
+  let falta = null;
+  for (let p = pasta; !existsSync(p); p = path.dirname(p)) falta = p;
+  return falta;
+}
+
+/** Desfaz as pastas vazias que esta chamada criou, de `pasta` até `criada`. */
+async function desfazer(criada, pasta) {
+  for (let p = pasta; ; p = path.dirname(p)) {
+    await fs.rmdir(p);
+    if (p === criada) return;
+  }
+}
+
+/** Cria `pasta` com a entrega inteira. @returns {Promise<boolean>} o destino precisou ser criado? */
+async function criar(pasta, arquivos, leiame, em) {
+  em.alvo = pasta;
+  if (existsSync(pasta)) throw new Error('já existe um arquivo com o nome da pasta');
+  const destino = path.dirname(pasta);
+  const criada = primeiraQueFalta(destino);
+  try {
+    await fs.mkdir(destino, { recursive: true });
+    await montar(pasta, arquivos, leiame, em);
+  } catch (erro) {
+    if (criada) await desfazer(criada, destino).catch(() => {});
+    throw erro;
+  }
+  return Boolean(criada);
+}
+
+/** O LEIA-ME da cópia é regravado quando muda (CRLF no lugar de LF não é mudança), sempre por último. */
+async function regravarLeiame(pasta, leiame, em) {
+  em.alvo = path.join(pasta, LEIAME);
+  const atual = await fs.readFile(em.alvo, 'utf8').catch(() => null);
+  if (atual == null || emLf(atual) !== leiame) await fs.writeFile(em.alvo, leiame, 'utf8');
+}
+
+/** As pastas anteriores ganham, na primeira linha do LEIA-ME, o aviso da pasta nova (um só). */
+async function avisarAnteriores(destino, anteriores, pastaNova, em) {
+  for (const { nome } of anteriores) {
+    em.alvo = path.join(destino, nome, LEIAME);
+    const atual = await fs.readFile(em.alvo, 'utf8').catch(() => null);
+    if (atual != null) await fs.writeFile(em.alvo, `${AVISO(pastaNova)}\n\n${atual.replace(AVISO_ANTERIOR, '')}`, 'utf8');
+  }
+}
+
+/** O LEIA-ME da pasta número `n` (1 = `<run>`; N = `<run>-reentrega-N`): um texto fixo, ou quem o monta. */
+const leiameDe = (leiame, n) => (typeof leiame === 'function' ? leiame(n) : leiame);
+
+/**
+ * Completa a pasta mais nova com o que falta, ou cria a pasta de reentrega quando algo mudou. A
+ * comparação é com o retrato do que foi copiado para ela; sem retrato, com os arquivos dela.
+ */
+async function atualizar({ destino, run, arquivos, ignorar, leiame, retratos }, existentes, em) {
+  const ultima = existentes.at(-1);
+  const pasta = path.join(destino.abs, ultima.nome);
+  const faltam = await oQueFalta(pasta, arquivos, ignorar, retratos?.[`${destino.rel}/${ultima.nome}`] ?? null);
+  if (!faltam) {
+    const nome = `${run}-reentrega-${ultima.n + 1}`;
+    await criar(path.join(destino.abs, nome), arquivos, leiameDe(leiame, ultima.n + 1), em);
+    await avisarAnteriores(destino.abs, existentes, `${destino.rel}/${nome}`, em);
+    return { tipo: 'reentrega', pasta: `${destino.rel}/${nome}` };
+  }
+  for (const a of faltam) {
+    em.alvo = path.join(pasta, a.pasta, a.nome);
+    await gravarNovo(em.alvo, a);
+  }
+  await regravarLeiame(pasta, leiameDe(leiame, ultima.n), em);
+  return { tipo: faltam.length ? 'completada' : 'igual', pasta: `${destino.rel}/${ultima.nome}`, novos: faltam.length };
+}
+
+/**
+ * Copia para o destino o que está pronto.
+ * @param {object} o
+ * @param {{ rel: string, abs: string }} o.destino a pasta escolhida, já validada · @param {string} o.run
+ * @param {object[]} o.arquivos o que é copiado agora: `{ pasta, nome, texto | de }`
+ * @param {Set<string>} o.ignorar `pasta/nome` do que a entrega tem e não é copiado agora
+ * @param {string|function(number): string} o.leiame o LEIA-ME da cópia, ou quem o monta para a pasta número N
+ * @param {object} [o.retratos] por pasta de cópia (relativa ao projeto), o retrato do que foi copiado
+ * @returns {Promise<object>} `{ tipo, pasta, novos, criouDestino }` — `tipo`: nova, igual,
+ *   completada ou reentrega; `pasta`: relativa ao projeto · ou `{ tipo: 'falha', arquivo }`, com o
+ *   caminho absoluto que não pôde ser gravado
+ */
+export async function copiar(o) {
+  const em = { alvo: o.destino.abs };
+  try {
+    const existentes = await pastasDaExecucao(o.destino.abs, o.run);
+    if (existentes.length) return await atualizar(o, existentes, em);
+    const criouDestino = await criar(path.join(o.destino.abs, o.run), o.arquivos, leiameDe(o.leiame, 1), em);
+    return { tipo: 'nova', pasta: `${o.destino.rel}/${o.run}`, criouDestino };
+  } catch {
+    return { tipo: 'falha', arquivo: em.alvo };
+  }
+}

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/documentos.mjs

@@ -0,0 +1,104 @@
+// Documentos na entrega: o item cujo formato tem a plataforma `documento` vai para a pasta
+// `documentos/`. Texto (`.md` ou `.txt`) vira Word, inteiro, com o perfil de documento oficial do
+// projeto, se existir: os mesmos bytes que o `documento.mjs` grava para o mesmo texto e o mesmo
+// perfil. Outro tipo de arquivo é copiado como está, com aviso. Erro ao converter (inclusive
+// perfil inválido) é pendência de `documentos`, que nunca vira ressalva: os outros canais seguem.
+// Este módulo só lê: quem grava é `gravar.mjs`.
+// Spec: fase-u3b-documento-word.md, decisão 9, regra 12 e §6 (repositório do OpenCrew).
+import { existsSync, promises as fs, statSync } from 'node:fs';
+import path from 'node:path';
+import { PERFIL, gerarDocx, lerPerfilDoProjeto } from '../documento.mjs';
+import { limpar } from './argumentos.mjs';
+
+/** A pasta da entrega e o tipo do arquivo que é (ou vai virar) um Word. */
+export const DOCUMENTOS = 'documentos';
+export const WORD = 'documento';
+const TEXTO = /\.(md|txt)$/i;
+
+export const MSG = {
+  copiado: (arquivo) => `${arquivo}: só converto .md ou .txt em Word. Copiei o arquivo como está.`,
+  erro: (arquivo, motivo) => `Não consegui gerar o Word de ${arquivo}: ${limpar(motivo).replace(/\.+$/, '')}.`,
+  aviso: (arquivo, aviso) => `${arquivo}: ${aviso}`,
+  semPerfil: 'Sem papel timbrado: este projeto não tem perfil de documento oficial. Para criar o seu: node _opencrew/core/scripts/documento.mjs --criar-perfil',
+  semTexto: 'o arquivo não tem texto para converter',
+  naoUtf8: 'o arquivo não está em UTF-8',
+};
+/** A linha de "O que não foi conferido" da entrega que tem um Word. */
+export const NAO_CONFERIDO = 'Como o documento abre no Word.';
+
+/** O tipo do arquivo em `documentos/`: texto que vira Word, ou cópia como está. */
+export const tipoDoDocumento = (arquivo) => (TEXTO.test(arquivo) ? WORD : 'copia');
+export const naoConferidoDoWord = (arquivos) => (arquivos.some((a) => a.pasta === DOCUMENTOS && a.tipo === WORD) ? [NAO_CONFERIDO] : []);
+
+/** O perfil do projeto, lido uma vez: `{}` sem perfil, `{ perfil, logotipo }` ou `{ erro }`. */
+async function perfilDoProjeto(raiz) {
+  const arquivo = path.join(raiz, PERFIL);
+  if (!existsSync(arquivo) || !statSync(arquivo).isFile()) return {};
+  try {
+    return await lerPerfilDoProjeto(raiz, PERFIL);
+  } catch (falha) {
+    return { erro: falha?.message ?? falha };
+  }
+}
+
+/** O texto do arquivo, em UTF-8; null quando os bytes não são UTF-8. */
+function decodificar(bytes) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/** O Word de um texto: `{ bytes, avisos }`, ou `{ erro }` com o motivo. */
+async function converter(copia, lido, gerar) {
+  if (lido.erro) return { erro: lido.erro };
+  try {
+    const texto = decodificar(await fs.readFile(copia.de));
+    if (texto === null) return { erro: MSG.naoUtf8 };
+    const documento = gerar({ texto, perfil: lido.perfil, logotipo: lido.logotipo });
+    return documento.vazio ? { erro: MSG.semTexto } : documento;
+  } catch (falha) {
+    return { erro: falha?.message ?? falha };
+  }
+}
+
+/** A cópia do texto vira o arquivo Word: cada origem é um grupo, para dois nomes iguais não se perderem. */
+const comoWord = (copia, bytes) => ({ ...copia, nome: copia.nome.replace(TEXTO, '.docx'), de: null, bytes, pastaDeOrigem: copia.de });
+const aviso = (texto) => ({ pasta: DOCUMENTOS, texto });
+const pendencia = (linha) => ({ linha, chave: null, preencher: null });
+
+/** Um arquivo de `documentos/` → o que entra em `copias`, `avisos` ou `pendencias`. */
+async function tratar(copia, lido, gerar, saida) {
+  if (copia.tipo !== WORD) {
+    saida.avisos.push(aviso(MSG.copiado(copia.origem)));
+    return saida.copias.push(copia);
+  }
+  const r = await converter(copia, lido, gerar);
+  if (r.erro) return saida.pendencias.push(pendencia(MSG.erro(copia.origem, r.erro)));
+  saida.avisos.push(...r.avisos.map((a) => aviso(MSG.aviso(copia.origem, a))));
+  return saida.copias.push(comoWord(copia, r.bytes));
+}
+
+/**
+ * Converte os textos que `separar` pôs em `documentos/`. Sem nenhum, devolve o que recebeu e não
+ * lê o perfil.
+ * @param {string} raiz a pasta do projeto
+ * @param {{ unidades: object[], copias: object[], avisos: object[] }} produtos o que `separar` devolve
+ * @param {function} [gerar] quem monta o Word (`gerarDocx`); os testes trocam para injetar um erro
+ * @returns {Promise<{ produtos: object, pendencias: object[] }>} `produtos`: os mesmos, com o Word
+ *   (`{ …, nome: '<nome>.docx', bytes }`) no lugar de cada texto convertido e os avisos da conversão ·
+ *   `pendencias`: uma por texto que não foi convertido, `{ linha, chave: null, preencher: null }`
+ */
+export async function converterDocumentos(raiz, produtos, gerar = gerarDocx) {
+  const saida = { copias: [], avisos: [...produtos.avisos], pendencias: [] };
+  if (!produtos.copias.some((c) => c.pasta === DOCUMENTOS)) return { produtos, pendencias: [] };
+  const lido = produtos.copias.some((c) => c.pasta === DOCUMENTOS && c.tipo === WORD) ? await perfilDoProjeto(raiz) : {};
+  for (const copia of produtos.copias) {
+    if (copia.pasta === DOCUMENTOS) await tratar(copia, lido, gerar, saida);
+    else saida.copias.push(copia);
+  }
+  // Sem perfil, o Word sai sem cabeçalho: a entrega diz, para ninguém procurar um timbre que não existe.
+  if (!lido.perfil && !lido.erro && saida.copias.some((c) => c.pasta === DOCUMENTOS && c.bytes)) saida.avisos.push(aviso(MSG.semPerfil));
+  return { produtos: { ...produtos, copias: saida.copias, avisos: saida.avisos }, pendencias: saida.pendencias };
+}

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

@@ -1,7 +1,8 @@
 // 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.
-// Spec: fase-u3a1-pasta-de-entrega.md, §4 e §6, ajuste da execução real (repositório do OpenCrew).
+// 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';
@@ -9,7 +10,7 @@ import { PRINCIPAL } from './leitor.mjs';
 import { ehServico, secoesDeRotulo, semComentarios } from './texto.mjs';
 
 export const MSG = {
-  fora: (blocos) => `Ficou fora do texto para colar: ${blocos.join(', ')}. Veja no arquivo de origem.`,
+  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.`,
 };
 
@@ -45,5 +46,5 @@ export function blocosFora(texto, formato = null) {
 
 /** 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), tela: MSG.foraNaTela(item.rel, 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

@@ -25,10 +25,10 @@ async function limparSobras({ entrega, tmp, antiga }) {
   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. */
+/** Grava um arquivo da entrega na pasta temporária: os bytes ou o texto gerados, 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');
+  if ((a.bytes ?? a.texto) != null) await fs.writeFile(destino, a.bytes ?? a.texto, 'utf8');
   else await fs.copyFile(a.de, destino);
 }
 
@@ -51,7 +51,7 @@ async function trocar({ entrega, tmp, antiga }, passo) {
 /**
  * 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 {object[]} arquivos `{ pasta, nome, texto | bytes | de }`
  * @param {{ leiame: string, relatorio: string }} textos
  * @returns {Promise<string|null>} null quando gravou tudo; senão, o caminho que não foi gravado
  */

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