@aksp/opencrew 1.9.0 → 1.11.0

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

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

@@ -0,0 +1,50 @@
+// Linha de comando do `documento.mjs`: as opções, a linha de uso e as mensagens em PT-BR.
+// Spec: fase-u3b-documento-word.md, §3 e §6 (repositório do OpenCrew).
+
+const COMANDO = 'node _opencrew/core/scripts/documento.mjs';
+export const USO = `Uso: ${COMANDO} "<arquivo.md>" [--saida <arquivo.docx|pasta>] [--perfil <arquivo>] [--sem-perfil] [--substituir] [--ajuda]\n     ${COMANDO} --criar-perfil`;
+
+export const MSG = {
+  desconhecida: (opcao) => `Opção desconhecida: ${opcao}.`,
+  semArquivo: 'Falta o arquivo de texto.',
+  maisDeUm: (n) => `Converto um arquivo por vez. Recebi ${n}.`,
+  naoEncontrei: (arquivo) => `Não encontrei ${arquivo}.`,
+  semTexto: (arquivo) => `${arquivo} não tem texto para converter.`,
+  naoUtf8: (arquivo) => `${arquivo} não está em UTF-8. Salve como UTF-8 e tente de novo.`,
+  extensao: (arquivo) => `Só converto texto em markdown (.md ou .txt). Recebi: ${arquivo}.`,
+  saida: (valor) => `A saída precisa ser um arquivo .docx ou uma pasta, dentro do projeto. Recebi: ${valor}.`,
+  jaExiste: (arquivo) => `Já existe ${arquivo}, diferente do que eu ia gravar. Para trocar, rode de novo com --substituir.`,
+  falha: (arquivo) => `Não consegui gravar ${arquivo}. Feche o arquivo no Word, ou espere a sincronização da pasta, e rode de novo.`,
+  semPerfil: (arquivo) => `Perfil não encontrado: ${arquivo}.`,
+  gerado: (arquivo) => `Documento gerado: ${arquivo}`,
+  igual: (arquivo) => `${arquivo} já existe e está igual. Nada a fazer.`,
+  perfil: (arquivo) => `Perfil: ${arquivo}`,
+  nenhumPerfil: `Perfil: nenhum (sem papel timbrado). Para criar o seu: ${COMANDO} --criar-perfil`,
+  avisos: 'Avisos:',
+  dicas: ['Para ter um PDF: abra o documento no Word e use Arquivo → Salvar como → PDF.', 'O Word é uma cópia do texto. O que você mudar nele não volta sozinho: altere o texto e gere de novo.'],
+  perfilCriado: (arquivo) => `Criei ${arquivo}. Abra, preencha o logotipo, o cabeçalho e o rodapé, e gere o documento de novo.`,
+  perfilJaExiste: (arquivo) => `${arquivo} já existe. Não mexi nele.`,
+};
+
+const COM_VALOR = /^--(saida|perfil)(?:=(.*))?$/s;
+const SEM_VALOR = { '--sem-perfil': 'semPerfil', '--substituir': 'substituir', '--ajuda': 'ajuda', '--criar-perfil': 'criarPerfil' };
+
+/** 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` → `{ arquivos, saida, perfil, semPerfil, substituir, ajuda, criarPerfil, desconhecida }`.
+ * Opção com valor vale como `--nome valor` e `--nome=valor`; `saida` e `perfil` ficam `undefined`
+ * quando a opção não veio. `desconhecida`: a primeira opção que o script não conhece, ou null.
+ */
+export function lerArgs(argv) {
+  const args = { arquivos: [], semPerfil: false, substituir: false, ajuda: false, criarPerfil: false, desconhecida: null };
+  for (let i = 0; i < argv.length; i++) {
+    const [, nome, colado] = argv[i].match(COM_VALOR) ?? [];
+    if (nome) args[nome] = colado ?? (i + 1 < argv.length && !argv[i + 1].startsWith('--') ? argv[++i] : '');
+    else if (Object.hasOwn(SEM_VALOR, argv[i])) args[SEM_VALOR[argv[i]]] = true;
+    else if (argv[i].startsWith('--')) args.desconhecida ??= argv[i];
+    else args.arquivos.push(argv[i]);
+  }
+  return args;
+}

package/templates/_opencrew/core/scripts/documento/corpo.mjs

@@ -0,0 +1,51 @@
+// O corpo do documento (`word/document.xml`): cada bloco lido do markdown vira um parágrafo ou uma
+// tabela, na ordem em que foi escrito; a seção (papel, margens, cabeçalho e rodapé) vai por último.
+// Spec: fase-u3b-documento-word.md, §4 e regra 3 (repositório do OpenCrew).
+import { tabelaDeAssinaturas, tabelaDeDados } from './tabelas.mjs';
+import { DECLARACAO, NS_R, NS_W, RECUO, borda, pPr, paragrafo, twips } from './xml.mjs';
+
+/** A4 em pé, em twips. */
+export const PAPEL = { largura: 11906, altura: 16838 };
+/** Distância do cabeçalho e do rodapé até a borda do papel: 1,2 cm. */
+const DA_BORDA = twips(1.2);
+const PENDURADO = 283;
+const VAZIO = '<w:p/>';
+
+/** Largura da área de texto, em twips: o papel menos as margens dos lados. */
+export const larguraDoTexto = (perfil) => PAPEL.largura - twips(perfil.margem_esquerda_cm) - twips(perfil.margem_direita_cm);
+
+const PARAGRAFO = {
+  centro: (b) => paragrafo({ estilo: b.estilo, quebra: b.quebra }, b.pedacos),
+  titulo: (b) => paragrafo({ estilo: `Heading${b.nivel}`, quebra: b.quebra }, b.pedacos),
+  item: (b) => paragrafo({ quebra: b.quebra, lista: b.nivel, recuo: { left: RECUO * (b.nivel + 1), hanging: PENDURADO } }, b.pedacos),
+  paragrafo: (b) => paragrafo({ quebra: b.quebra, recuo: b.recuo ? { left: RECUO } : null }, b.pedacos, { b: b.negrito }),
+  regua: (b) => `<w:p>${pPr({ quebra: b.quebra, bordas: borda('bottom', { cor: 'AAAAAA', espaco: 1 }) })}</w:p>`,
+};
+const TABELA = { tabela: tabelaDeDados, assinaturas: tabelaDeAssinaturas };
+const ehTabela = (bloco) => Boolean(bloco && TABELA[bloco.tipo]);
+
+/** Tabela: a quebra de página vai num parágrafo vazio antes; no fim, ou antes de outra tabela, um depois. */
+function comTabela(bloco, proximo, largura) {
+  const antes = bloco.quebra ? `<w:p>${pPr({ quebra: true })}</w:p>` : '';
+  return `${antes}${TABELA[bloco.tipo](bloco, largura)}${!proximo || ehTabela(proximo) ? VAZIO : ''}`;
+}
+
+function secao(perfil, referencias) {
+  const margens = { top: twips(perfil.margem_superior_cm), right: twips(perfil.margem_direita_cm), bottom: twips(perfil.margem_inferior_cm), left: twips(perfil.margem_esquerda_cm), header: DA_BORDA, footer: DA_BORDA, gutter: 0 };
+  const lados = Object.entries(margens).map(([lado, valor]) => ` w:${lado}="${valor}"`).join('');
+  const cabecalho = referencias.cabecalho ? `<w:headerReference w:type="default" r:id="${referencias.cabecalho}"/>` : '';
+  const rodape = referencias.rodape ? `<w:footerReference w:type="default" r:id="${referencias.rodape}"/>` : '';
+  return `<w:sectPr>${cabecalho}${rodape}<w:pgSz w:w="${PAPEL.largura}" w:h="${PAPEL.altura}"/><w:pgMar${lados}/></w:sectPr>`;
+}
+
+/**
+ * @param {object[]} blocos os de `lerMarkdown`
+ * @param {object} perfil o perfil completo (com os padrões)
+ * @param {{ cabecalho?: string, rodape?: string }} referencias o `r:id` de cada parte que existe
+ * @returns {string} o XML de `word/document.xml`
+ */
+export function montarCorpo(blocos, perfil, referencias) {
+  const largura = larguraDoTexto(perfil);
+  const partes = blocos.map((bloco, i) => (ehTabela(bloco) ? comTabela(bloco, blocos[i + 1], largura) : PARAGRAFO[bloco.tipo](bloco)));
+  return `${DECLARACAO}<w:document xmlns:w="${NS_W}" xmlns:r="${NS_R}"><w:body>${partes.join('')}${secao(perfil, referencias)}</w:body></w:document>`;
+}

package/templates/_opencrew/core/scripts/documento/estilos.mjs

@@ -0,0 +1,42 @@
+// As partes fixas do documento: estilos (`word/styles.xml`), a lista com marcador
+// (`word/numbering.xml`) e os ajustes (`word/settings.xml`). Do perfil só entram a fonte e o
+// tamanho do corpo; os outros tamanhos e as cores são os do documento oficial de referência.
+// Spec: fase-u3b-documento-word.md, §4 (repositório do OpenCrew).
+import { DECLARACAO, NS_W, RECUO, pPr, rPr } from './xml.mjs';
+
+const IDIOMA = 'pt-BR';
+const CINZA = '333333';
+/** Entrelinha 1,15 (276/240), automática, e 5 pt depois de cada parágrafo. */
+const DO_CORPO = { espaco: { after: 100, line: 276, lineRule: 'auto' }, jc: 'both' };
+
+/** Os estilos além do `Normal`: `[id, nome, parágrafo, letra]`. Espaços em vigésimos de ponto. */
+const ESTILOS = [
+  ['Titulo', 'Título do documento', { espaco: { before: 160, after: 80 }, jc: 'center' }, { b: true, sz: 14 }],
+  ['Subtitulo', 'Subtítulo do documento', { espaco: { before: 0, after: 320 }, jc: 'center' }, { i: true, cor: CINZA, sz: 10 }],
+  ['Heading1', 'heading 1', { keepNext: true, espaco: { before: 280, after: 80 }, jc: 'left', topico: 0 }, { b: true, caps: true, sz: 12 }],
+  ['Heading2', 'heading 2', { keepNext: true, espaco: { before: 200, after: 60 }, jc: 'left', topico: 1 }, { b: true, sz: 11 }],
+  ['Heading3', 'heading 3', { keepNext: true, espaco: { before: 160, after: 40 }, jc: 'left', topico: 2 }, { b: true, i: true, cor: CINZA, sz: 10.5 }],
+];
+
+const estilo = ([id, nome, paragrafo, letra]) =>
+  `<w:style w:type="paragraph" w:styleId="${id}"><w:name w:val="${nome}"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/>${pPr(paragrafo)}${rPr(letra)}</w:style>`;
+
+/** @param {{ fonte: string, tamanho_corpo_pt: number }} perfil */
+export function montarEstilos(perfil) {
+  const letra = { fonte: perfil.fonte, sz: perfil.tamanho_corpo_pt, idioma: IDIOMA };
+  const padroes = `<w:docDefaults><w:rPrDefault>${rPr(letra)}</w:rPrDefault><w:pPrDefault/></w:docDefaults>`;
+  const normal = `<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/><w:qFormat/>${pPr(DO_CORPO)}${rPr(letra)}</w:style>`;
+  return `${DECLARACAO}<w:styles xmlns:w="${NS_W}">${padroes}${normal}${ESTILOS.map(estilo).join('')}</w:styles>`;
+}
+
+/** Um nível da lista: marcador `•`, recuo de 0,75 cm por nível. */
+const nivel = (n) =>
+  `<w:lvl w:ilvl="${n}"><w:start w:val="1"/><w:numFmt w:val="bullet"/><w:lvlText w:val="•"/><w:lvlJc w:val="left"/>${pPr({ recuo: { left: RECUO * (n + 1), hanging: 283 } })}</w:lvl>`;
+
+/** A lista com marcador, de dois níveis; é o `numId` 1 de todo item de lista. */
+export const montarNumeracao = () =>
+  `${DECLARACAO}<w:numbering xmlns:w="${NS_W}"><w:abstractNum w:abstractNumId="0"><w:multiLevelType w:val="hybridMultilevel"/>${nivel(0)}${nivel(1)}</w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num></w:numbering>`;
+
+/** Modo de compatibilidade 15: o Word não abre o arquivo em "Modo de Compatibilidade". */
+export const montarAjustes = () =>
+  `${DECLARACAO}<w:settings xmlns:w="${NS_W}"><w:compat><w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="15"/></w:compat></w:settings>`;

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

@@ -0,0 +1,44 @@
+// Gravação do documento Word: montado na memória, gravado num temporário ao lado do destino e
+// renomeado. Em falha não fica arquivo pela metade nem temporário. Um Word diferente que já está
+// lá só é trocado quando o usuário autoriza; um igual não é tocado. Nada é apagado.
+// Spec: fase-u3b-documento-word.md, regra 12 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/** O que já está no destino: os bytes do arquivo, `null` (nada) ou `false` (não é um arquivo legível). */
+async function atual(destino, disco) {
+  try {
+    return await disco.readFile(destino);
+  } catch (erro) {
+    return erro.code === 'ENOENT' ? null : false;
+  }
+}
+
+/** Grava pelo temporário; se algo falha, o temporário (que é deste script) sai e o destino fica como estava. */
+async function trocar(destino, bytes, disco) {
+  const temporario = `${destino}.opencrew-tmp`;
+  try {
+    await disco.mkdir(path.dirname(destino), { recursive: true });
+    await disco.writeFile(temporario, bytes);
+    await disco.rename(temporario, destino);
+    return true;
+  } catch {
+    await fs.rm(temporario, { force: true }).catch(() => {});
+    return false;
+  }
+}
+
+/**
+ * @param {string} destino caminho absoluto do `.docx`
+ * @param {Buffer} bytes
+ * @param {{ substituir?: boolean, disco?: object }} [opcoes] `disco`: as funções de `fs.promises`
+ * @returns {Promise<'gravado'|'igual'|'diferente'|'falha'>} `igual`: já existe com os mesmos bytes,
+ *   nada foi gravado · `diferente`: já existe outro e `substituir` não veio, nada foi gravado
+ */
+export async function gravarDocx(destino, bytes, { substituir = false, disco = fs } = {}) {
+  const existente = await atual(destino, disco);
+  if (existente === false) return 'falha';
+  if (existente?.equals(bytes)) return 'igual';
+  if (existente && !substituir) return 'diferente';
+  return (await trocar(destino, bytes, disco)) ? 'gravado' : 'falha';
+}

package/templates/_opencrew/core/scripts/documento/linha.mjs

@@ -0,0 +1,58 @@
+// O texto de uma linha: negrito, itálico, link e imagem. Devolve os pedaços com a sua letra, sem
+// mudar nenhuma palavra: o que não é marcação em par sai como foi escrito.
+// Spec: fase-u3b-documento-word.md, regra 7 (repositório do OpenCrew).
+
+// Guardam, durante a leitura, os sinais que não são marcação (`\*`, `\_` e os de dentro de um
+// endereço). São caracteres de controle: o texto já chega aqui sem nenhum deles.
+const ASTERISCO = String.fromCharCode(1);
+const SUBLINHADO = String.fromCharCode(2);
+const guardar = (texto) => texto.split('*').join(ASTERISCO).split('_').join(SUBLINHADO);
+const devolver = (texto) => texto.split(ASTERISCO).join('*').split(SUBLINHADO).join('_');
+
+const LINK = /(!?)\[([^\]]*)\]\(([^)\s]+)\)/g;
+const ENDERECO = /\bhttps?:\/\/\S+/g;
+// Só em par, na mesma linha, colado ao texto, e com espaço, pontuação ou borda do lado de fora.
+const ENFASE = /(?<![\p{L}\p{N}*_\\])(\*\*\*|___|\*\*|__|\*|_)(?=\S)(.+?)(?<=\S)\1(?![\p{L}\p{N}*_])/u;
+
+/** `[texto](url)` vira `texto (url)` (ou só a URL, se o texto é ela); imagem fica como está. */
+function semLinks(texto, contagem) {
+  return texto.replace(LINK, (tudo, imagem, rotulo, url) => {
+    if (imagem) contagem.imagens++;
+    if (imagem) return guardar(tudo);
+    return rotulo === url ? guardar(url) : `${rotulo} (${guardar(url)})`;
+  });
+}
+
+/** Parte o texto nos trechos com e sem ênfase; a ênfase de fora vale para a de dentro. */
+function partir(texto, letra) {
+  const m = ENFASE.exec(texto);
+  if (!m) return texto ? [{ texto, ...letra }] : [];
+  const dentro = { b: letra.b || m[1].length >= 2, i: letra.i || m[1].length !== 2 };
+  return [...partir(texto.slice(0, m.index), letra), ...partir(m[2], dentro), ...partir(texto.slice(m.index + m[0].length), letra)];
+}
+
+/** Junta pedaços vizinhos com a mesma letra. */
+function juntar(pedacos) {
+  const saida = [];
+  for (const p of pedacos) {
+    const ultimo = saida.at(-1);
+    if (ultimo && ultimo.b === p.b && ultimo.i === p.i) ultimo.texto += p.texto;
+    else saida.push({ ...p });
+  }
+  return saida;
+}
+
+/**
+ * Lê uma linha de texto.
+ * @param {string} texto a linha, já sem o sinal de título ou de lista
+ * @param {{ imagens: number }} contagem soma as imagens que ficaram como texto
+ * @returns {{ texto: string, b: boolean, i: boolean }[]}
+ */
+export function lerLinha(texto, contagem = { imagens: 0 }) {
+  const semEscapes = texto.split('\\*').join(ASTERISCO).split('\\_').join(SUBLINHADO);
+  const protegido = semLinks(semEscapes, contagem).replace(ENDERECO, guardar);
+  return juntar(partir(protegido, { b: false, i: false })).map((p) => ({ ...p, texto: devolver(p.texto) }));
+}
+
+/** O texto como foi escrito, sem ler marcação nenhuma. */
+export const literal = (texto) => (texto ? [{ texto, b: false, i: false }] : []);

package/templates/_opencrew/core/scripts/documento/marcacoes.mjs

@@ -0,0 +1,55 @@
+// As três marcações de documento: linha que começa por `:::` na primeira coluna. Título e
+// subtítulo centralizados, quebra de página e bloco de assinaturas. O que não é uma delas fica
+// como texto, igual ao que foi escrito, com aviso.
+// Spec: fase-u3b-documento-word.md, regra 8 (repositório do OpenCrew).
+import { lerLinha } from './linha.mjs';
+
+const MARCACAO = /^:::\s*(\S*)\s*(.*)$/;
+const CENTRO = { titulo: 'Titulo', subtitulo: 'Subtitulo' };
+
+export const ehMarcacao = (linha) => linha.startsWith(':::');
+
+/** Nome sem diferenciar maiúsculas e acentos: `Quebra-de-Página` → `quebra-de-pagina`. */
+const normalizar = (nome) => nome.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
+
+/** `Nome | Cargo` → `{ nome, cargo }`; sem barra, só o nome. Nada mais é interpretado. */
+function pessoa(linha) {
+  const barra = linha.indexOf('|');
+  if (barra < 0) return { nome: linha.trim(), cargo: '' };
+  return { nome: linha.slice(0, barra).trim(), cargo: linha.slice(barra + 1).trim() };
+}
+
+/** Bloco de assinaturas: vai até a linha `:::`. Sem ela, a linha de abertura fica como texto. */
+function lerAssinaturas(linhas, i, estado) {
+  const fim = linhas.findIndex((l, n) => n > i && l.trim() === ':::');
+  if (fim < 0) {
+    estado.avisos.semFim++;
+    estado.texto(linhas[i]);
+    return i + 1;
+  }
+  const pessoas = linhas.slice(i + 1, fim).filter((l) => l.trim()).map(pessoa);
+  if (pessoas.length) estado.por({ tipo: 'assinaturas', pessoas });
+  return fim + 1;
+}
+
+/**
+ * Lê a marcação da linha `i` e devolve a linha em que o próximo bloco começa.
+ * @param {string[]} linhas
+ * @param {number} i
+ * @param {object} estado o de `lerMarkdown`: `por`, `texto`, `quebrar` e `avisos`
+ */
+export function lerMarcacao(linhas, i, estado) {
+  const [, nomeEscrito, resto] = MARCACAO.exec(linhas[i].trimEnd());
+  const nome = normalizar(nomeEscrito);
+  if (Object.hasOwn(CENTRO, nome) && resto) {
+    estado.por({ tipo: 'centro', estilo: CENTRO[nome], pedacos: lerLinha(resto.trim(), estado.avisos) });
+  } else if (nome === 'quebra-de-pagina' && !resto) {
+    estado.quebrar();
+  } else if (nome === 'assinaturas' && !resto) {
+    return lerAssinaturas(linhas, i, estado);
+  } else {
+    estado.avisos.desconhecidas++;
+    estado.texto(linhas[i]);
+  }
+  return i + 1;
+}

package/templates/_opencrew/core/scripts/documento/markdown.mjs

@@ -0,0 +1,92 @@
+// Leitura do texto em markdown: uma linha, um bloco. Devolve os blocos na ordem em que foram
+// escritos (título, parágrafo, item de lista, tabela, linha horizontal, assinaturas) e a contagem
+// dos avisos de conversão. Não numera, não reordena e não corrige nada.
+// Spec: fase-u3b-documento-word.md, regras 4 a 9 (repositório do OpenCrew).
+import { lerLinha, literal } from './linha.mjs';
+import { ehMarcacao, lerMarcacao } from './marcacoes.mjs';
+import { limpar } from './xml.mjs';
+
+const REGUA = /^(-{3,}|\*{3,}|_{3,})$/;
+const TITULO = /^(#{1,6})[ \t]+(\S.*)$/;
+const ITEM = /^(\s*)[-*][ \t]+(\S.*)$/;
+const SEPARADORA = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/;
+const BARRA = /(?<!\\)\|/;
+const CHAVE = /^[A-Za-z_][\w-]*:(\s|$)/;
+const recuado = (inicio) => /^(\t| {2,})/.test(inicio);
+
+/** Tira o frontmatter: da primeira linha `---` à próxima, só com `chave: valor` e continuações. */
+function semFrontmatter(linhas) {
+  if (linhas[0]?.trimEnd() !== '---') return linhas;
+  const fim = linhas.findIndex((l, i) => i > 0 && l.trimEnd() === '---');
+  if (fim < 0) return linhas;
+  const meio = linhas.slice(1, fim).filter((l) => l.trim());
+  return meio.every((l) => CHAVE.test(l) || /^\s+\S/.test(l)) ? linhas.slice(fim + 1) : linhas;
+}
+
+const ehSeparadora = (linha) => linha != null && linha.includes('|') && linha.includes('-') && SEPARADORA.test(linha);
+
+/** As células de uma linha de tabela: sem as barras das pontas; `\|` dá a barra. */
+function celulas(linha) {
+  const miolo = linha.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '');
+  return miolo.split(BARRA).map((c) => c.trim().split('\\|').join('|'));
+}
+
+/** Tabela: cabeçalho, linha separadora e as linhas seguintes que têm barra. Vale a linha mais longa. */
+function lerTabela(linhas, i, estado) {
+  let fim = i + 2;
+  while (fim < linhas.length && linhas[fim].trim() && linhas[fim].includes('|')) fim++;
+  const brutas = [linhas[i], ...linhas.slice(i + 2, fim)].map(celulas);
+  const colunas = Math.max(...brutas.map((l) => l.length));
+  const completas = brutas.map((l) => [...l, ...Array(colunas - l.length).fill('')]);
+  estado.por({ tipo: 'tabela', linhas: completas.map((l) => l.map((c) => lerLinha(c, estado.avisos))) });
+  return fim;
+}
+
+/** Uma linha sozinha: linha horizontal, título, item de lista ou parágrafo. */
+function lerBloco(linha, avisos) {
+  const texto = linha.trim();
+  if (REGUA.test(texto)) return { tipo: 'regua' };
+  const titulo = TITULO.exec(texto);
+  if (titulo && titulo[1].length <= 3) return { tipo: 'titulo', nivel: titulo[1].length, pedacos: lerLinha(titulo[2], avisos) };
+  if (titulo) return { tipo: 'paragrafo', negrito: true, pedacos: lerLinha(titulo[2], avisos) };
+  const item = ITEM.exec(linha);
+  if (item) return { tipo: 'item', nivel: recuado(item[1]) ? 1 : 0, pedacos: lerLinha(item[2].trimEnd(), avisos) };
+  return { tipo: 'paragrafo', recuo: recuado(linha), pedacos: lerLinha(texto, avisos) };
+}
+
+/** Onde os blocos se juntam: a quebra de página pedida vale para o próximo bloco, uma vez só. */
+function novoEstado() {
+  const estado = { blocos: [], avisos: { imagens: 0, desconhecidas: 0, semFim: 0, invalidos: 0 }, quebra: false };
+  estado.por = (bloco) => {
+    estado.blocos.push(estado.quebra ? { ...bloco, quebra: true } : bloco);
+    estado.quebra = false;
+  };
+  estado.texto = (linha) => estado.por({ tipo: 'paragrafo', pedacos: literal(linha.trim()) });
+  estado.quebrar = () => { estado.quebra = estado.blocos.length > 0; };
+  return estado;
+}
+
+/** Consome o bloco que começa na linha `i`; devolve a linha em que o próximo começa. */
+function consumir(linhas, i, estado) {
+  const linha = linhas[i];
+  if (!linha.trim()) return i + 1;
+  if (ehMarcacao(linha)) return lerMarcacao(linhas, i, estado);
+  if (linha.includes('|') && ehSeparadora(linhas[i + 1])) return lerTabela(linhas, i, estado);
+  estado.por(lerBloco(linha, estado.avisos));
+  return i + 1;
+}
+
+/**
+ * @param {string} bruto o texto do arquivo (CRLF ou LF, com ou sem BOM)
+ * @returns {{ blocos: object[], avisos: { imagens: number, desconhecidas: number, semFim: number, invalidos: number } }}
+ *   bloco: `{ tipo, pedacos | linhas | pessoas, nivel?, recuo?, negrito?, quebra? }`
+ */
+export function lerMarkdown(bruto) {
+  const semBom = bruto.charCodeAt(0) === 0xfeff ? bruto.slice(1) : bruto;
+  const { texto, removidos } = limpar(semBom.replace(/\r\n?/g, '\n'));
+  const linhas = semFrontmatter(texto.split('\n'));
+  const estado = novoEstado();
+  estado.avisos.invalidos = removidos;
+  for (let i = 0; i < linhas.length;) i = consumir(linhas, i, estado);
+  return { blocos: estado.blocos, avisos: estado.avisos };
+}

package/templates/_opencrew/core/scripts/documento/pacote.mjs

@@ -0,0 +1,82 @@
+// O pacote do documento Word: junta as partes, os tipos de conteúdo e as relações, na ordem
+// fixa, e fecha o zip. Não toca o disco: recebe o texto, o perfil já lido e o logotipo em bytes.
+// Spec: fase-u3b-documento-word.md, regras 2 a 4 e 9 (repositório do OpenCrew).
+import { larguraDoTexto, montarCorpo } from './corpo.mjs';
+import { montarAjustes, montarEstilos, montarNumeracao } from './estilos.mjs';
+import { lerMarkdown } from './markdown.mjs';
+import { PADRAO } from './perfil.mjs';
+import { lerPng } from './png.mjs';
+import { montarCabecalho, montarRodape, temCabecalho, temRodape } from './timbre.mjs';
+import { DECLARACAO, NS_R } from './xml.mjs';
+import { zipar } from './zip.mjs';
+
+const WORD = 'application/vnd.openxmlformats-officedocument.wordprocessingml';
+const NS_PACOTE = 'http://schemas.openxmlformats.org/package/2006';
+/** As partes de `word/` que têm tipo próprio e são alvo de uma relação do documento, na ordem do zip. */
+const PARTES = [['styles', 'styles'], ['settings', 'settings'], ['numbering', 'numbering'], ['header1', 'header'], ['footer1', 'footer']];
+
+const plural = (n, um, varios) => (n === 1 ? um : varios.replace('{n}', n));
+/** Os avisos de conversão, na ordem da spec; cada um diz a quantidade. */
+function avisosDe(c) {
+  return [
+    c.imagens && plural(c.imagens, '1 imagem não incluída: o Word não leva imagem no texto.', '{n} imagens não incluídas: o Word não leva imagem no texto.'),
+    c.desconhecidas && plural(c.desconhecidas, '1 linha com marcação desconhecida (`:::`) ficou como texto.', '{n} linhas com marcação desconhecida (`:::`) ficaram como texto.'),
+    c.semFim && plural(c.semFim, 'Bloco de assinaturas sem a linha `:::` no fim: ficou como texto.', '{n} blocos de assinaturas sem a linha `:::` no fim: ficaram como texto.'),
+    c.invalidos && plural(c.invalidos, '1 caractere inválido removido.', '{n} caracteres inválidos removidos.'),
+  ].filter(Boolean);
+}
+
+const relacao = (id, tipo, alvo) => `<Relationship Id="${id}" Type="${NS_R}/${tipo}" Target="${alvo}"/>`;
+const relacoes = (lista) => `${DECLARACAO}<Relationships xmlns="${NS_PACOTE}/relationships">${lista.join('')}</Relationships>`;
+
+function tiposDeConteudo(nomes) {
+  const padroes = [['rels', 'application/vnd.openxmlformats-package.relationships+xml'], ['xml', 'application/xml'], ['png', 'image/png']];
+  const proprios = [['document', 'document.main'], ...PARTES].filter(([nome]) => nomes.includes(nome));
+  const porExtensao = padroes.map(([extensao, tipo]) => `<Default Extension="${extensao}" ContentType="${tipo}"/>`).join('');
+  const porParte = proprios.map(([nome, tipo]) => `<Override PartName="/word/${nome}.xml" ContentType="${WORD}.${tipo}+xml"/>`).join('');
+  return `${DECLARACAO}<Types xmlns="${NS_PACOTE}/content-types">${porExtensao}${porParte}</Types>`;
+}
+
+/** O que existe além das partes fixas, e o `rId` de cada parte ligada ao documento. */
+function planejar(perfil, imagem) {
+  const existe = { styles: true, settings: true, numbering: true, header1: temCabecalho(perfil, imagem), footer1: temRodape(perfil) };
+  const ligadas = PARTES.filter(([nome]) => existe[nome]).map(([nome, tipo], i) => ({ nome, tipo, id: `rId${i + 1}` }));
+  const idDe = (nome) => ligadas.find((l) => l.nome === nome)?.id;
+  return { ligadas, referencias: { cabecalho: idDe('header1'), rodape: idDe('footer1') } };
+}
+
+/** As partes do zip, na ordem da regra 2. */
+function montarPartes(blocos, perfil, logotipo) {
+  const imagem = logotipo ? lerPng(logotipo) : null;
+  const { ligadas, referencias } = planejar(perfil, imagem);
+  const largura = larguraDoTexto(perfil);
+  const partes = [
+    ['[Content_Types].xml', tiposDeConteudo(['document', ...ligadas.map((l) => l.nome)])],
+    ['_rels/.rels', relacoes([relacao('rId1', 'officeDocument', 'word/document.xml')])],
+    ['word/document.xml', montarCorpo(blocos, perfil, referencias)],
+    ['word/_rels/document.xml.rels', relacoes(ligadas.map((l) => relacao(l.id, l.tipo, `${l.nome}.xml`)))],
+    ['word/styles.xml', montarEstilos(perfil)],
+    ['word/settings.xml', montarAjustes()],
+    ['word/numbering.xml', montarNumeracao()],
+  ];
+  if (referencias.cabecalho) partes.push(['word/header1.xml', montarCabecalho(perfil, largura, imagem, 'rId1')]);
+  if (imagem) partes.push(['word/_rels/header1.xml.rels', relacoes([relacao('rId1', 'image', 'media/logo.png')])], ['word/media/logo.png', Buffer.from(logotipo)]);
+  if (referencias.rodape) partes.push(['word/footer1.xml', montarRodape(perfil, largura)]);
+  return partes.map(([nome, bytes]) => ({ nome, bytes }));
+}
+
+/**
+ * Gera o documento Word na memória. O mesmo texto, o mesmo perfil e o mesmo logotipo dão os
+ * mesmos bytes.
+ * @param {object} entrada
+ * @param {string} entrada.texto o markdown (CRLF ou LF, com ou sem BOM)
+ * @param {object} [entrada.perfil] o perfil já lido (`lerPerfil`); sem ele, valem os padrões
+ * @param {Uint8Array} [entrada.logotipo] os bytes do PNG do cabeçalho; sem eles, não há logotipo
+ * @returns {{ bytes: Buffer, avisos: string[], vazio: boolean }} `vazio`: o texto não tem nada a
+ *   converter (só frontmatter, ou só linhas vazias)
+ */
+export function gerarDocx({ texto, perfil, logotipo }) {
+  const { blocos, avisos } = lerMarkdown(texto);
+  const completo = { ...PADRAO, ...perfil };
+  return { bytes: zipar(montarPartes(blocos, completo, logotipo)), avisos: avisosDe(avisos), vazio: blocos.length === 0 };
+}