@aksp/opencrew 1.9.0 → 1.11.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;
+  }
+}

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

@@ -0,0 +1,57 @@
+// As tabelas do corpo: a tabela de dados (bordas finas, primeira linha em negrito sobre cinza,
+// colunas iguais) e o bloco de assinaturas (sem bordas, duas por linha, a ímpar no centro).
+// Nenhuma linha parte entre páginas. Toda célula termina em parágrafo.
+// Spec: fase-u3b-documento-word.md, §4 e regra 3 (repositório do OpenCrew).
+import { RECUO, borda, paragrafo, twips } from './xml.mjs';
+
+const LADOS = ['top', 'left', 'bottom', 'right', 'insideH', 'insideV'];
+const BORDAS = `<w:tblBorders>${LADOS.map((lado) => borda(lado, { cor: 'CCCCCC' })).join('')}</w:tblBorders>`;
+const MARGENS = '<w:tblCellMar><w:top w:w="40" w:type="dxa"/><w:left w:w="100" w:type="dxa"/><w:bottom w:w="40" w:type="dxa"/><w:right w:w="100" w:type="dxa"/></w:tblCellMar>';
+export const SEM_MARGENS = '<w:tblCellMar><w:top w:w="0" w:type="dxa"/><w:left w:w="0" w:type="dxa"/><w:bottom w:w="0" w:type="dxa"/><w:right w:w="0" w:type="dxa"/></w:tblCellMar>';
+const FUNDO = '<w:shd w:val="clear" w:color="auto" w:fill="F0F0F0"/>';
+const NA_CELULA = { espaco: { after: 0 }, jc: 'left' };
+/** Espaço em branco para a assinatura à mão, acima da linha: 36 pt. */
+const ANTES_DA_LINHA = 720;
+const RECUO_DA_SOZINHA = twips(4);
+
+/**
+ * A moldura de uma tabela: propriedades, grade e linhas, nessa ordem.
+ * @param {number[]} colunas largura de cada coluna, em twips
+ * @param {{ bordas?: string, margens?: string }} partes o que vai em `tblPr`, além da largura e do leiaute fixo
+ * @param {string[]} linhas o XML das células de cada linha
+ */
+export function tabela(colunas, { bordas = '', margens = '' }, linhas) {
+  const largura = colunas.reduce((a, b) => a + b, 0);
+  const grade = colunas.map((w) => `<w:gridCol w:w="${w}"/>`).join('');
+  const corpo = linhas.map((l) => `<w:tr><w:trPr><w:cantSplit/></w:trPr>${l}</w:tr>`).join('');
+  return `<w:tbl><w:tblPr><w:tblW w:w="${largura}" w:type="dxa"/>${bordas}<w:tblLayout w:type="fixed"/>${margens}</w:tblPr><w:tblGrid>${grade}</w:tblGrid>${corpo}</w:tbl>`;
+}
+
+/** Uma célula: largura, o que mais vier em `tcPr` (na ordem do formato) e os parágrafos. */
+export const celula = (largura, propriedades, paragrafos) => `<w:tc><w:tcPr><w:tcW w:w="${largura}" w:type="dxa"/>${propriedades}</w:tcPr>${paragrafos}</w:tc>`;
+
+/** Tabela de dados, na largura da área de texto, com colunas iguais. */
+export function tabelaDeDados(bloco, larguraDoTexto) {
+  const coluna = Math.floor(larguraDoTexto / bloco.linhas[0].length);
+  const linhas = bloco.linhas.map((linha, n) => linha.map((pedacos) => celula(coluna, n === 0 ? FUNDO : '', paragrafo(NA_CELULA, pedacos, { b: n === 0 }))).join(''));
+  return tabela(bloco.linhas[0].map(() => coluna), { bordas: BORDAS, margens: MARGENS }, linhas);
+}
+
+/** Uma assinatura: a linha (borda de cima), o nome em negrito e caixa alta por formatação, e o cargo. */
+function assinatura({ nome, cargo }, recuo) {
+  const daLinha = { bordas: borda('top', { sz: 6, cor: '000000', espaco: 1 }), espaco: { before: ANTES_DA_LINHA, after: 0 }, recuo: { left: recuo, right: recuo }, jc: 'center' };
+  const doNome = paragrafo(daLinha, [{ texto: nome }], { b: true, caps: true });
+  return cargo ? `${doNome}${paragrafo({ espaco: { after: 0 }, jc: 'center' }, [{ texto: cargo }])}` : doNome;
+}
+
+/** Bloco de assinaturas: duas por linha, na ordem escrita; a que sobra ocupa a linha inteira. */
+export function tabelaDeAssinaturas(bloco, larguraDoTexto) {
+  const coluna = Math.floor(larguraDoTexto / 2);
+  const linhas = [];
+  for (let i = 0; i < bloco.pessoas.length; i += 2) {
+    const par = bloco.pessoas.slice(i, i + 2);
+    if (par.length === 2) linhas.push(par.map((p) => celula(coluna, '', assinatura(p, RECUO))).join(''));
+    else linhas.push(celula(coluna * 2, '<w:gridSpan w:val="2"/>', assinatura(par[0], RECUO_DA_SOZINHA)));
+  }
+  return tabela([coluna, coluna], { margens: SEM_MARGENS }, linhas);
+}

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

@@ -0,0 +1,64 @@
+// O papel timbrado: cabeçalho (`word/header1.xml`: logotipo e até três linhas, com uma linha
+// preta embaixo) e rodapé (`word/footer1.xml`: o texto do perfil e "Página X de Y").
+// Spec: fase-u3b-documento-word.md, §4 e regra 2 (repositório do OpenCrew).
+import { SEM_MARGENS, celula, tabela } from './tabelas.mjs';
+import { DECLARACAO, NS_R, NS_W, borda, pPr, paragrafo, rPr, trecho, twips } from './xml.mjs';
+
+const NS_WP = 'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing';
+const NS_A = 'http://schemas.openxmlformats.org/drawingml/2006/main';
+const NS_PIC = 'http://schemas.openxmlformats.org/drawingml/2006/picture';
+/** Unidades do desenho (EMU) por centímetro. */
+const EMU_POR_CM = 360000;
+/** Folga entre o logotipo e as linhas do cabeçalho: 0,4 cm. */
+const FOLGA = twips(0.4);
+const SEM_ESPACO = { espaco: { after: 0 }, jc: 'left' };
+const LINHAS = [['cabecalho_1', { b: true, sz: 12 }], ['cabecalho_2', { sz: 10 }], ['cabecalho_3', { cor: '666666', sz: 10 }]];
+const DO_RODAPE = { sz: 8.5 };
+
+/** O cabeçalho existe quando há logotipo ou alguma das três linhas. */
+export const temCabecalho = (perfil, logotipo) => Boolean(logotipo) || LINHAS.some(([chave]) => perfil[chave]);
+/** O rodapé existe quando há texto de rodapé ou número de página. */
+export const temRodape = (perfil) => Boolean(perfil.rodape) || perfil.numero_pagina;
+
+/** A imagem, na largura do perfil e na altura proporcional. `rId`: a relação com `media/logo.png`. */
+function desenho(perfil, logotipo, rId) {
+  const cx = Math.round(perfil.logotipo_largura_cm * EMU_POR_CM);
+  const cy = Math.round((cx * logotipo.altura) / logotipo.largura);
+  const figura = `<pic:pic><pic:nvPicPr><pic:cNvPr id="1" name="logo.png"/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill><a:blip r:embed="${rId}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${cx}" cy="${cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic>`;
+  const moldura = `<wp:extent cx="${cx}" cy="${cy}"/><wp:docPr id="1" name="Logotipo"/><wp:cNvGraphicFramePr><a:graphicFrameLocks noChangeAspect="1"/></wp:cNvGraphicFramePr>`;
+  return `<w:r><w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0">${moldura}<a:graphic><a:graphicData uri="${NS_PIC}">${figura}</a:graphicData></a:graphic></wp:inline></w:drawing></w:r>`;
+}
+
+/**
+ * @param {object} perfil o perfil completo
+ * @param {number} largura a largura da área de texto, em twips
+ * @param {{ largura: number, altura: number }|null} logotipo as medidas do PNG, em pontos da imagem
+ * @param {string} rId a relação da imagem, em `word/_rels/header1.xml.rels`
+ */
+export function montarCabecalho(perfil, largura, logotipo, rId) {
+  const linhas = LINHAS.filter(([chave]) => perfil[chave]).map(([chave, letra]) => paragrafo(SEM_ESPACO, [{ texto: perfil[chave] }], letra));
+  const texto = linhas.join('') || paragrafo(SEM_ESPACO);
+  const daImagem = logotipo ? twips(perfil.logotipo_largura_cm) + FOLGA : 0;
+  const centro = '<w:vAlign w:val="center"/>';
+  const imagem = logotipo ? celula(daImagem, centro, `<w:p>${pPr(SEM_ESPACO)}${desenho(perfil, logotipo, rId)}</w:p>`) : '';
+  const colunas = logotipo ? [daImagem, largura - daImagem] : [largura];
+  const bordas = `<w:tblBorders>${borda('bottom', { sz: 8, cor: '000000' })}</w:tblBorders>`;
+  const quadro = tabela(colunas, { bordas, margens: SEM_MARGENS }, [`${imagem}${celula(colunas.at(-1), centro, texto)}`]);
+  const espacos = `xmlns:w="${NS_W}" xmlns:r="${NS_R}" xmlns:wp="${NS_WP}" xmlns:a="${NS_A}" xmlns:pic="${NS_PIC}"`;
+  return `${DECLARACAO}<w:hdr ${espacos}>${quadro}${paragrafo(SEM_ESPACO)}</w:hdr>`;
+}
+
+/** Um campo do Word (`PAGE`, `NUMPAGES`), com "1" como valor até o Word calcular. */
+function campo(instrucao) {
+  const marca = (tipo) => `<w:r>${rPr(DO_RODAPE)}<w:fldChar w:fldCharType="${tipo}"/></w:r>`;
+  const comando = `<w:r>${rPr(DO_RODAPE)}<w:instrText xml:space="preserve"> ${instrucao} </w:instrText></w:r>`;
+  return `${marca('begin')}${comando}${marca('separate')}${trecho('1', DO_RODAPE)}${marca('end')}`;
+}
+
+/** @param {object} perfil o perfil completo · @param {number} largura a da área de texto, em twips */
+export function montarRodape(perfil, largura) {
+  const props = { bordas: borda('top', { cor: 'AAAAAA', espaco: 4 }), tabs: `<w:tab w:val="right" w:pos="${largura}"/>`, espaco: { after: 0 }, jc: 'left' };
+  const texto = trecho(perfil.rodape, { ...DO_RODAPE, i: true, cor: '666666' });
+  const pagina = perfil.numero_pagina ? `${trecho('\tPágina ', DO_RODAPE)}${campo('PAGE')}${trecho(' de ', DO_RODAPE)}${campo('NUMPAGES')}` : '';
+  return `${DECLARACAO}<w:ftr xmlns:w="${NS_W}"><w:p>${pPr(props)}${texto}${pagina}</w:p></w:ftr>`;
+}

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

@@ -0,0 +1,95 @@
+// Tijolos do XML do Word: texto seguro (escape e caracteres proibidos), medidas, e as propriedades
+// de parágrafo e de letra com os filhos sempre na ordem que o formato exige.
+// Spec: fase-u3b-documento-word.md, regras 3 (g) e 4 (repositório do OpenCrew).
+
+export const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+export const NS_R = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+export const DECLARACAO = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+/** Um nível de recuo: 0,75 cm. */
+export const RECUO = 425;
+
+/** Centímetros → twips (1/20 de ponto). */
+export const twips = (cm) => Math.round(cm * 566.93);
+/** Pontos → meios-pontos (a unidade do tamanho de letra). */
+export const meios = (pt) => Math.round(pt * 2);
+
+const ehAlta = (c) => c >= 0xd800 && c <= 0xdbff;
+const ehBaixa = (c) => c >= 0xdc00 && c <= 0xdfff;
+/** Caractere que o XML 1.0 não aceita (as metades de par substituto são vistas à parte). */
+const proibido = (c) => (c < 0x20 && c !== 0x09 && c !== 0x0a && c !== 0x0d) || c === 0xfffe || c === 0xffff || ehAlta(c) || ehBaixa(c);
+
+/**
+ * Tira o que não pode estar num XML 1.0: controles (menos tabulação e quebras de linha), U+FFFE,
+ * U+FFFF e metade solta de par substituto.
+ * @returns {{ texto: string, removidos: number }}
+ */
+export function limpar(texto) {
+  let saida = '';
+  let removidos = 0;
+  for (let i = 0; i < texto.length; i++) {
+    const c = texto.charCodeAt(i);
+    if (ehAlta(c) && ehBaixa(texto.charCodeAt(i + 1))) saida += texto[i] + texto[++i];
+    else if (proibido(c)) removidos++;
+    else saida += texto[i];
+  }
+  return { texto: saida, removidos };
+}
+
+/** Texto para dentro do XML, em conteúdo ou em atributo. */
+export const esc = (texto) => limpar(String(texto)).texto.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+const attrs = (o) => Object.entries(o).map(([nome, valor]) => ` w:${nome}="${valor}"`).join('');
+
+/** Uma borda simples: `borda('top', { sz: 4, cor: 'CCCCCC' })`. `sz` em oitavos de ponto. */
+export const borda = (lado, { sz = 4, cor, espaco = 0 }) => `<w:${lado} w:val="single" w:sz="${sz}" w:space="${espaco}" w:color="${cor}"/>`;
+
+/**
+ * Propriedades do parágrafo, na ordem do formato: estilo, keepNext, quebra de página antes, lista,
+ * bordas, tabulações, espaço, recuo, alinhamento e nível de tópico.
+ * `espaco`: `{ before, after, line, lineRule }` · `recuo`: `{ left, right, hanging }` (twips).
+ */
+export function pPr(o = {}) {
+  const partes = [
+    o.estilo && `<w:pStyle w:val="${o.estilo}"/>`,
+    o.keepNext && '<w:keepNext/>',
+    o.quebra && '<w:pageBreakBefore/>',
+    o.lista != null && `<w:numPr><w:ilvl w:val="${o.lista}"/><w:numId w:val="1"/></w:numPr>`,
+    o.bordas && `<w:pBdr>${o.bordas}</w:pBdr>`,
+    o.tabs && `<w:tabs>${o.tabs}</w:tabs>`,
+    o.espaco && `<w:spacing${attrs(o.espaco)}/>`,
+    o.recuo && `<w:ind${attrs(o.recuo)}/>`,
+    o.jc && `<w:jc w:val="${o.jc}"/>`,
+    o.topico != null && `<w:outlineLvl w:val="${o.topico}"/>`,
+  ].filter(Boolean);
+  return partes.length ? `<w:pPr>${partes.join('')}</w:pPr>` : '';
+}
+
+/** Propriedades da letra, na ordem do formato. `sz` em pontos; `fonte` já validada. */
+export function rPr(o = {}) {
+  const partes = [
+    o.fonte && `<w:rFonts w:ascii="${esc(o.fonte)}" w:hAnsi="${esc(o.fonte)}" w:cs="${esc(o.fonte)}"/>`,
+    o.b && '<w:b/>',
+    o.i && '<w:i/>',
+    o.caps && '<w:caps/>',
+    o.cor && `<w:color w:val="${o.cor}"/>`,
+    o.sz && `<w:sz w:val="${meios(o.sz)}"/><w:szCs w:val="${meios(o.sz)}"/>`,
+    o.idioma && `<w:lang w:val="${o.idioma}"/>`,
+  ].filter(Boolean);
+  return partes.length ? `<w:rPr>${partes.join('')}</w:rPr>` : '';
+}
+
+/** O texto de um trecho: `w:t` (sempre com `xml:space="preserve"`) e `w:tab` em cada tabulação. */
+const conteudo = (texto) => texto.split('\t').map((parte) => (parte ? `<w:t xml:space="preserve">${esc(parte)}</w:t>` : '')).join('<w:tab/>');
+
+/** Um trecho de texto com a sua letra. Texto vazio não gera trecho. */
+export const trecho = (texto, letra = {}) => (texto ? `<w:r>${rPr(letra)}${conteudo(texto)}</w:r>` : '');
+
+/**
+ * Um parágrafo a partir dos pedaços lidos da linha (`[{ texto, b, i }]`).
+ * @param {object} props o que `pPr` recebe
+ * @param {object} [letra] letra comum a todos os pedaços (soma com o negrito e o itálico de cada um)
+ */
+export function paragrafo(props, pedacos = [], letra = {}) {
+  const trechos = pedacos.map((p) => trecho(p.texto, { ...letra, b: letra.b || p.b, i: letra.i || p.i })).join('');
+  return `<w:p>${pPr(props)}${trechos}</w:p>`;
+}

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

@@ -0,0 +1,86 @@
+// Contêiner zip do documento Word, escrito à mão: toda entrada sem compressão (método 0), com
+// CRC-32 próprio e data fixa (1980-01-01 00:00). O mesmo conteúdo dá os mesmos bytes, em qualquer
+// máquina e em qualquer versão do Node. Não importa `node:zlib`.
+// Spec: fase-u3b-documento-word.md, regra 1 (repositório do OpenCrew).
+
+const TABELA = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? (c >>> 1) ^ 0xedb88320 : c >>> 1;
+  return c >>> 0;
+});
+
+/** CRC-32 (o do zip e do PNG) de um bloco de bytes. */
+export function crc32(bytes) {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = TABELA[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+const VERSAO = 20;
+const DATA = 0x0021; // 1980-01-01
+const HORA = 0;
+/** Bit 11 (nome em UTF-8): só quando o nome sai do ASCII. */
+const marcas = (nome) => (nome.length === Buffer.byteLength(nome, 'utf8') ? 0 : 0x0800);
+
+function cabecalhoLocal(e) {
+  const b = Buffer.alloc(30);
+  b.writeUInt32LE(0x04034b50, 0);
+  b.writeUInt16LE(VERSAO, 4);
+  b.writeUInt16LE(marcas(e.nome), 6);
+  b.writeUInt16LE(0, 8); // método 0: sem compressão
+  b.writeUInt16LE(HORA, 10);
+  b.writeUInt16LE(DATA, 12);
+  b.writeUInt32LE(e.crc, 14);
+  b.writeUInt32LE(e.bytes.length, 18);
+  b.writeUInt32LE(e.bytes.length, 22);
+  b.writeUInt16LE(e.nomeEmBytes.length, 26);
+  return Buffer.concat([b, e.nomeEmBytes]);
+}
+
+function registroCentral(e) {
+  const b = Buffer.alloc(46);
+  b.writeUInt32LE(0x02014b50, 0);
+  b.writeUInt16LE(VERSAO, 4);
+  b.writeUInt16LE(VERSAO, 6);
+  b.writeUInt16LE(marcas(e.nome), 8);
+  b.writeUInt16LE(0, 10);
+  b.writeUInt16LE(HORA, 12);
+  b.writeUInt16LE(DATA, 14);
+  b.writeUInt32LE(e.crc, 16);
+  b.writeUInt32LE(e.bytes.length, 20);
+  b.writeUInt32LE(e.bytes.length, 24);
+  b.writeUInt16LE(e.nomeEmBytes.length, 28);
+  b.writeUInt32LE(e.inicio, 42);
+  return Buffer.concat([b, e.nomeEmBytes]);
+}
+
+function registroFinal(total, tamanho, inicio) {
+  const b = Buffer.alloc(22);
+  b.writeUInt32LE(0x06054b50, 0);
+  b.writeUInt16LE(total, 8);
+  b.writeUInt16LE(total, 10);
+  b.writeUInt32LE(tamanho, 12);
+  b.writeUInt32LE(inicio, 16);
+  return b;
+}
+
+/**
+ * Monta o zip, na ordem recebida.
+ * @param {{ nome: string, bytes: Buffer|string }[]} partes nomes com `/`; texto vai em UTF-8
+ * @returns {Buffer}
+ */
+export function zipar(partes) {
+  const locais = [];
+  const centrais = [];
+  let inicio = 0;
+  for (const parte of partes) {
+    const bytes = Buffer.isBuffer(parte.bytes) ? parte.bytes : Buffer.from(parte.bytes, 'utf8');
+    const e = { nome: parte.nome, nomeEmBytes: Buffer.from(parte.nome, 'utf8'), bytes, crc: crc32(bytes), inicio };
+    const local = cabecalhoLocal(e);
+    locais.push(local, bytes);
+    centrais.push(registroCentral(e));
+    inicio += local.length + bytes.length;
+  }
+  const diretorio = Buffer.concat(centrais);
+  return Buffer.concat([...locais, diretorio, registroFinal(partes.length, diretorio.length, inicio)]);
+}

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

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Documento Word: converte um texto em markdown (.md ou .txt) num `.docx`, com as mesmas palavras
+// e os mesmos números, na mesma ordem. Com o perfil de documento oficial do projeto, sai em papel
+// timbrado: cabeçalho com logotipo, rodapé com "Página X de Y", margens e letra do perfil.
+// Uso (na pasta do projeto): node _opencrew/core/scripts/documento.mjs "<arquivo.md>"
+//   [--saida <arquivo.docx|pasta>] [--perfil <arquivo>] [--sem-perfil] [--substituir] [--ajuda]
+//   node _opencrew/core/scripts/documento.mjs --criar-perfil
+//   --saida: onde gravar (padrão: ao lado do texto, com o mesmo nome e `.docx`); a pasta é criada.
+//   --perfil: outro arquivo de perfil (padrão: `_opencrew/_memory/documento-oficial.md`, se existir).
+//   --sem-perfil: ignora o perfil do projeto (sem timbre, com os padrões).
+//   --substituir: autoriza trocar um `.docx` diferente que já existe no destino.
+//   --criar-perfil: cria o perfil do projeto a partir do modelo, só se ele não existir.
+// Grava só o `.docx` pedido (por um temporário ao lado, renomeado no fim) e, com --criar-perfil, o
+// perfil que faltava. Nunca apaga nada. Um `.docx` igual ao que seria gravado não é tocado.
+// Última linha da saída: DOCUMENTO:OK (o Word está no destino) · PERFIL:CRIADO ou PERFIL:JA-EXISTE
+// (com --criar-perfil).
+// Código de saída: 0 quando a linha final sai, e em --ajuda · 1 = erro: uma mensagem em PT-BR, sem
+// linha DOCUMENTO: e nada gravado.
+// Para outros scripts: `gerarDocx({ texto, perfil, logotipo })` → `{ bytes, avisos }`, sem tocar o
+// disco; `lerPerfilDoProjeto(raiz, arquivo)` → `{ perfil, logotipo }` ou `{ erro }`.
+// Spec: fase-u3b-documento-word.md (repositório do OpenCrew).
+import { existsSync, promises as fs, statSync } from 'node:fs';
+import path from 'node:path';
+import { MSG as COMUM, dentroDoProjeto, ehPrincipal, relativoAoProjeto } from './comum.mjs';
+import { MSG, USO, lerArgs, limpar } from './documento/argumentos.mjs';
+import { gravarDocx } from './documento/gravar.mjs';
+import { gerarDocx } from './documento/pacote.mjs';
+import { PERFIL, criarPerfil, lerPerfilDoProjeto } from './documento/projeto.mjs';
+
+export { gerarDocx } from './documento/pacote.mjs';
+export { lerPerfil } from './documento/perfil.mjs';
+export { PERFIL, lerPerfilDoProjeto } from './documento/projeto.mjs';
+
+const TEXTO = /\.(md|txt)$/i;
+const ehPasta = (p) => existsSync(p) && statSync(p).isDirectory();
+const ehArquivo = (p) => existsSync(p) && statSync(p).isFile();
+const erro = (mensagem, comUso = false) => ({ erro: mensagem, comUso });
+
+/** O arquivo de texto pedido: um só, dentro do projeto, `.md` ou `.txt`, e que existe. */
+function conferirOrigem(raiz, arquivos) {
+  if (arquivos.length === 0) return erro(MSG.semArquivo, true);
+  if (arquivos.length > 1) return erro(MSG.maisDeUm(arquivos.length), true);
+  if (!ehPasta(path.join(raiz, '_opencrew'))) return erro(COMUM.semRaiz);
+  if (!dentroDoProjeto(raiz, arquivos[0])) return erro(COMUM.foraDoProjeto(limpar(arquivos[0])));
+  const rel = relativoAoProjeto(raiz, arquivos[0]);
+  if (!TEXTO.test(rel)) return erro(MSG.extensao(rel));
+  return ehArquivo(path.resolve(raiz, arquivos[0])) ? { rel, abs: path.resolve(raiz, arquivos[0]) } : erro(MSG.naoEncontrei(rel));
+}
+
+/** Onde o Word vai: ao lado do texto, ou no arquivo `.docx` ou na pasta de `--saida`. */
+function conferirDestino(raiz, saida, origem) {
+  const nome = `${path.basename(origem.abs).replace(TEXTO, '')}.docx`;
+  if (saida === undefined) return { destino: path.join(path.dirname(origem.abs), nome) };
+  const recusada = erro(MSG.saida(limpar(saida)));
+  if (!saida.trim() || !dentroDoProjeto(raiz, saida)) return recusada;
+  const alvo = path.resolve(raiz, saida);
+  if (/\.docx$/i.test(alvo)) return ehPasta(alvo) ? recusada : { destino: alvo };
+  if (ehPasta(alvo)) return { destino: path.join(alvo, nome) };
+  return existsSync(alvo) || path.extname(alvo) ? recusada : { destino: path.join(alvo, nome) };
+}
+
+/** O arquivo de perfil que vale nesta chamada (`arquivo` fica sem valor quando não há perfil). */
+function conferirPerfil(raiz, args) {
+  if (args.semPerfil) return {};
+  if (args.perfil === undefined) return ehArquivo(path.join(raiz, PERFIL)) ? { arquivo: PERFIL } : {};
+  if (!dentroDoProjeto(raiz, args.perfil)) return erro(COMUM.foraDoProjeto(limpar(args.perfil)));
+  return ehArquivo(path.resolve(raiz, args.perfil)) ? { arquivo: args.perfil } : erro(MSG.semPerfil(limpar(args.perfil)));
+}
+
+/** Tudo o que a chamada pede, conferido antes de ler ou gravar qualquer coisa. */
+function conferir(raiz, args) {
+  const origem = conferirOrigem(raiz, args.arquivos);
+  if (origem.erro) return origem;
+  const destino = conferirDestino(raiz, args.saida, origem);
+  const perfil = conferirPerfil(raiz, args);
+  return destino.erro ? destino : perfil.erro ? perfil : { origem, destino: destino.destino, perfil: perfil.arquivo };
+}
+
+/** O texto do arquivo, em UTF-8; `null` quando os bytes não são UTF-8. */
+async function lerTexto(arquivo) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(await fs.readFile(arquivo));
+  } catch (falha) {
+    if (falha instanceof TypeError) return null;
+    throw falha;
+  }
+}
+
+/** Monta o documento na memória: `{ bytes, avisos }`, ou `{ erro }` com a mensagem. */
+async function montar(raiz, pedido) {
+  const texto = await lerTexto(pedido.origem.abs);
+  if (texto === null) return erro(MSG.naoUtf8(pedido.origem.rel));
+  const lido = pedido.perfil ? await lerPerfilDoProjeto(raiz, pedido.perfil) : {};
+  if (lido.erro) return erro(lido.erro);
+  const documento = gerarDocx({ texto, perfil: lido.perfil, logotipo: lido.logotipo });
+  return documento.vazio ? erro(MSG.semTexto(pedido.origem.rel)) : documento;
+}
+
+function relatorio(raiz, pedido, estado, avisos) {
+  const destino = relativoAoProjeto(raiz, pedido.destino);
+  return [
+    estado === 'igual' ? MSG.igual(destino) : MSG.gerado(destino),
+    pedido.perfil ? MSG.perfil(relativoAoProjeto(raiz, pedido.perfil)) : MSG.nenhumPerfil,
+    ...(avisos.length ? [MSG.avisos, ...avisos.map((a) => `- ${a}`)] : []),
+    ...MSG.dicas,
+    'DOCUMENTO:OK',
+  ];
+}
+
+/** Converte e grava; devolve as linhas da saída e o código. */
+async function converter(raiz, args, disco) {
+  const pedido = conferir(raiz, args);
+  if (pedido.erro) return { linhas: [pedido.erro, ...(pedido.comUso ? [USO] : [])], code: 1 };
+  const documento = await montar(raiz, pedido);
+  if (documento.erro) return { linhas: [documento.erro], code: 1 };
+  const estado = await gravarDocx(pedido.destino, documento.bytes, { substituir: args.substituir, disco });
+  const destino = relativoAoProjeto(raiz, pedido.destino);
+  if (estado === 'diferente') return { linhas: [MSG.jaExiste(destino)], code: 1 };
+  if (estado === 'falha') return { linhas: [MSG.falha(destino)], code: 1 };
+  return { linhas: relatorio(raiz, pedido, estado, documento.avisos), code: 0 };
+}
+
+async function criar(raiz) {
+  if (!ehPasta(path.join(raiz, '_opencrew'))) return { linhas: [COMUM.semRaiz], code: 1 };
+  const criado = await criarPerfil(raiz);
+  return { linhas: criado ? [MSG.perfilCriado(PERFIL), 'PERFIL:CRIADO'] : [MSG.perfilJaExiste(PERFIL), 'PERFIL:JA-EXISTE'], code: 0 };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps] `cwd` (a pasta do projeto), `escrever` e `disco` (as funções de
+ *   `fs.promises` usadas na gravação do `.docx`)
+ * @returns {Promise<number>} 0 = a linha final saiu (ou `--ajuda`) · 1 = erro (uma mensagem em
+ *   PT-BR, sem linha `DOCUMENTO:`, nada gravado)
+ */
+export async function main(argv, { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`), disco = fs } = {}) {
+  const args = lerArgs(argv);
+  const sair = ({ linhas, code }) => linhas.forEach((l) => escrever(l)) ?? code;
+  if (args.ajuda) return sair({ linhas: [USO], code: 0 });
+  if (args.desconhecida) return sair({ linhas: [MSG.desconhecida(limpar(args.desconhecida)), USO], code: 1 });
+  try {
+    return sair(args.criarPerfil ? await criar(cwd) : await converter(cwd, args, disco));
+  } catch (falha) {
+    return sair({ linhas: [`Não consegui gerar o documento: ${limpar(falha?.message ?? falha)}`], code: 1 });
+  }
+}
+
+if (ehPrincipal(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}

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

@@ -6,7 +6,9 @@ import path from 'node:path';
 import { lerFrontmatter, lerTexto } from '../verificar/leitura.mjs';
 
 /** Pasta do canal → nome no LEIA-ME, na ordem em que as seções aparecem. */
-export const CANAIS = { instagram: 'Instagram', linkedin: 'LinkedIn', blog: 'Blog', email: 'E-mail', whatsapp: 'WhatsApp', twitter: 'X/Twitter', youtube: 'YouTube' };
+export const CANAIS = { instagram: 'Instagram', linkedin: 'LinkedIn', blog: 'Blog', email: 'E-mail', whatsapp: 'WhatsApp', twitter: 'X/Twitter', youtube: 'YouTube', documentos: 'Documentos' };
+/** Plataforma cuja pasta tem outro nome (fase-u3b-documento-word.md, regra 12). */
+const PASTA_DA_PLATAFORMA = { documento: 'documentos' };
 export const OUTROS = 'outros';
 export const EDITAVEIS = 'editaveis';
 export const ehCanal = (pasta) => Object.hasOwn(CANAIS, pasta);
@@ -23,13 +25,15 @@ async function plataformaEm(raiz, pasta, formato) {
 /**
  * Canal de um formato: o `platform:` de `_opencrew/best-practices.local/<formato>.md`, quando o
  * arquivo o declara; senão, o do core. Sem formato, sem best-practice, sem `platform:` ou com
- * plataforma que não é uma das sete pastas: null (o arquivo vai para `outros/`).
+ * plataforma que não é uma das oito pastas: null (o arquivo vai para `outros/`). A plataforma
+ * `documento` é a pasta `documentos`.
  */
 export async function canalDoFormato(raiz, formato) {
   if (!formato || !/^[a-z0-9-]+$/.test(formato)) return null;
   const local = await plataformaEm(raiz, ['best-practices.local'], formato);
   const plataforma = local ?? (await plataformaEm(raiz, ['core', 'best-practices'], formato));
-  return plataforma && ehCanal(plataforma) ? plataforma : null;
+  const pasta = Object.hasOwn(PASTA_DA_PLATAFORMA, plataforma ?? '') ? PASTA_DA_PLATAFORMA[plataforma] : plataforma;
+  return pasta && ehCanal(pasta) ? pasta : null;
 }
 
 const PASTAS_DE_SERVICO = new Set(['entrega', 'entrega.tmp', 'export']);

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

@@ -11,8 +11,8 @@ import path from 'node:path';
 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: o texto gerado, ou os do arquivo de origem. */
-export const bytesDe = async (a) => (a.texto != null ? Buffer.from(a.texto, 'utf8') : fs.readFile(a.de));
+/** 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')));