@aksp/opencrew 1.9.0 → 1.10.0

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

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

@@ -0,0 +1,70 @@
+// O perfil de documento oficial: um arquivo de texto do projeto, com linhas `chave: valor`.
+// Aqui ele é lido e validado, sem tocar o disco; o logotipo é conferido em `projeto.mjs`.
+// Spec: fase-u3b-documento-word.md, §3 e regra 10 (repositório do OpenCrew).
+
+/** O que vale quando a chave não vem, ou vem vazia. */
+export const PADRAO = Object.freeze({
+  logotipo: '', logotipo_largura_cm: 2.5, cabecalho_1: '', cabecalho_2: '', cabecalho_3: '', rodape: '', numero_pagina: true,
+  margem_esquerda_cm: 3, margem_direita_cm: 2, margem_superior_cm: 2.5, margem_inferior_cm: 2.5, fonte: 'Arial', tamanho_corpo_pt: 11,
+});
+
+export const MSG = {
+  chave: (n, chave) => `Perfil, linha ${n}: não conheço a chave ${chave}.`,
+  valor: (n, chave, esperado, valor) => `Perfil, linha ${n}: ${chave} precisa ser ${esperado}. Recebi: ${valor}.`,
+};
+
+// `chave: valor`; o espaço depois dos dois-pontos é opcional, mas um endereço (`https://…`) não é chave.
+const LINHA = /^([a-z0-9_]+):(?!\/\/)[ \t]*(.*)$/;
+const NUMERO = /^\d+(?:[.,]\d+)?$/;
+const numero = (valor) => (NUMERO.test(valor) ? Number(valor.replace(',', '.')) : NaN);
+const texto = { esperado: '', ler: (valor) => valor };
+const deUmASeis = { esperado: 'um número de 1 a 6', ler: (valor) => (numero(valor) >= 1 && numero(valor) <= 6 ? numero(valor) : undefined) };
+const SIM_OU_NAO = { sim: true, nao: false, 'não': false };
+
+/** Como cada chave é lida: `ler` devolve o valor, ou `undefined` quando ele não serve. */
+const CHAVES = {
+  logotipo: texto,
+  logotipo_largura_cm: deUmASeis,
+  cabecalho_1: texto,
+  cabecalho_2: texto,
+  cabecalho_3: texto,
+  rodape: texto,
+  numero_pagina: { esperado: 'sim ou nao', ler: (valor) => (Object.hasOwn(SIM_OU_NAO, valor.toLowerCase()) ? SIM_OU_NAO[valor.toLowerCase()] : undefined) },
+  margem_esquerda_cm: deUmASeis,
+  margem_direita_cm: deUmASeis,
+  margem_superior_cm: deUmASeis,
+  margem_inferior_cm: deUmASeis,
+  fonte: { esperado: 'um nome com até 40 letras, dígitos e espaços', ler: (valor) => (/^[\p{L}\p{N} ]{1,40}$/u.test(valor) ? valor : undefined) },
+  tamanho_corpo_pt: { esperado: 'um número de 8 a 14 (aceita meio ponto)', ler: (valor) => (numero(valor) >= 8 && numero(valor) <= 14 && Number.isInteger(numero(valor) * 2) ? numero(valor) : undefined) },
+};
+
+/** Tira as aspas em volta do valor, se as duas pontas têm a mesma. */
+function semAspas(valor) {
+  const v = valor.trim();
+  return v.length >= 2 && (v[0] === '"' || v[0] === "'") && v.at(-1) === v[0] ? v.slice(1, -1).trim() : v;
+}
+
+/**
+ * Lê o texto do perfil. Só valem as linhas `chave: valor` cuja chave tem letras minúsculas,
+ * dígitos e `_`, a partir da primeira coluna; qualquer outra linha é comentário. Valor vazio vale
+ * o padrão. Chave repetida: vale a última.
+ * @param {string} bruto
+ * @returns {{ perfil: object, linhas: Record<string, number>, erro: string|null }} `perfil` com os
+ *   padrões aplicados; `linhas`: o número da linha de cada chave lida; `erro`: a mensagem em PT-BR
+ */
+export function lerPerfil(bruto) {
+  const perfil = { ...PADRAO };
+  const linhas = {};
+  const semBom = bruto.charCodeAt(0) === 0xfeff ? bruto.slice(1) : bruto;
+  for (const [i, linha] of semBom.split(/\r\n?|\n/).entries()) {
+    const [, chave, escrito = ''] = LINHA.exec(linha.trimEnd()) ?? [];
+    if (!chave) continue;
+    if (!Object.hasOwn(CHAVES, chave)) return { perfil, linhas, erro: MSG.chave(i + 1, chave) };
+    linhas[chave] = i + 1;
+    const valor = semAspas(escrito);
+    const lido = valor === '' ? PADRAO[chave] : CHAVES[chave].ler(valor);
+    if (lido === undefined) return { perfil, linhas, erro: MSG.valor(i + 1, chave, CHAVES[chave].esperado, valor) };
+    perfil[chave] = lido;
+  }
+  return { perfil, linhas, erro: null };
+}

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

@@ -0,0 +1,20 @@
+// Leitura mínima de um PNG: a assinatura de 8 bytes e a largura e a altura do bloco IHDR, para a
+// proporção do logotipo. A imagem não é aberta nem regravada: vai para o documento como veio.
+// Spec: fase-u3b-documento-word.md, §3 (repositório do OpenCrew).
+
+const ASSINATURA = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Tamanho máximo do logotipo: 2 MB. */
+export const MAXIMO = 2 * 1024 * 1024;
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {{ largura: number, altura: number }|null} null quando não é um PNG
+ */
+export function lerPng(bytes) {
+  const b = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (b.length < 24 || ASSINATURA.some((valor, i) => b[i] !== valor)) return null;
+  if (b.toString('latin1', 12, 16) !== 'IHDR') return null;
+  const largura = b.readUInt32BE(16);
+  const altura = b.readUInt32BE(20);
+  return largura > 0 && altura > 0 ? { largura, altura } : null;
+}

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

@@ -0,0 +1,60 @@
+// O perfil de documento oficial no disco do projeto: onde mora, como nasce do modelo (e nunca é
+// sobrescrito) e a leitura do logotipo que ele cita. Perfil inválido não gera documento: o erro
+// diz a linha.
+// Spec: fase-u3b-documento-word.md, regras 10 e 11 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dentroDoProjeto } from '../comum.mjs';
+import { lerPerfil } from './perfil.mjs';
+import { MAXIMO, lerPng } from './png.mjs';
+
+/** Onde o perfil do projeto mora (o `update` não toca esta pasta). */
+export const PERFIL = '_opencrew/_memory/documento-oficial.md';
+/** O modelo do pacote, ao lado dos scripts: `_opencrew/core/modelos/documento-oficial.md`. */
+const MODELO = fileURLToPath(new URL('../../modelos/documento-oficial.md', import.meta.url));
+
+export const MSG = {
+  semLogotipo: (n, arquivo) => `Perfil, linha ${n}: não encontrei o logotipo ${arquivo}.`,
+  logotipo: (n, arquivo) => `Perfil, linha ${n}: o logotipo precisa ser um arquivo PNG de até 2 MB, dentro do projeto. Recebi: ${arquivo}.`,
+};
+
+/** Os bytes do logotipo citado no perfil: `{ bytes }`, ou `{ erro }` com a mensagem da linha. */
+async function lerLogotipo(raiz, arquivo, linha) {
+  if (!dentroDoProjeto(raiz, arquivo)) return { erro: MSG.logotipo(linha, arquivo) };
+  const info = await fs.stat(path.resolve(raiz, arquivo)).catch(() => null);
+  if (!info) return { erro: MSG.semLogotipo(linha, arquivo) };
+  if (!info.isFile() || info.size > MAXIMO) return { erro: MSG.logotipo(linha, arquivo) };
+  const bytes = await fs.readFile(path.resolve(raiz, arquivo));
+  return lerPng(bytes) ? { bytes } : { erro: MSG.logotipo(linha, arquivo) };
+}
+
+/**
+ * Lê o perfil de um arquivo do projeto, com o logotipo que ele cita.
+ * @param {string} raiz a pasta do projeto
+ * @param {string} arquivo o perfil, relativo à raiz ou absoluto (já conferido: existe e fica no projeto)
+ * @returns {Promise<{ perfil?: object, logotipo?: Buffer, erro?: string }>}
+ */
+export async function lerPerfilDoProjeto(raiz, arquivo) {
+  const { perfil, linhas, erro } = lerPerfil(await fs.readFile(path.resolve(raiz, arquivo), 'utf8'));
+  if (erro) return { erro };
+  if (!perfil.logotipo) return { perfil };
+  const logotipo = await lerLogotipo(raiz, perfil.logotipo, linhas.logotipo);
+  return logotipo.erro ? { erro: logotipo.erro } : { perfil, logotipo: logotipo.bytes };
+}
+
+/**
+ * Cria o perfil do projeto a partir do modelo, só se ele não existir.
+ * @returns {Promise<boolean>} true quando criou; false quando já existia (e não foi tocado)
+ */
+export async function criarPerfil(raiz) {
+  const destino = path.join(raiz, PERFIL);
+  await fs.mkdir(path.dirname(destino), { recursive: true });
+  try {
+    await fs.writeFile(destino, await fs.readFile(MODELO), { flag: 'wx' });
+    return true;
+  } catch (erro) {
+    if (erro.code === 'EEXIST') return false;
+    throw erro;
+  }
+}