@aksp/opencrew 1.9.0 → 1.10.0

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

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

@@ -17,7 +17,7 @@ const ehPasta = async (p) => fs.stat(p).then((s) => s.isDirectory(), () => false
 /** Grava um arquivo que ainda não existe ali: se existir, falha (nunca por cima). */
 async function gravarNovo(alvo, a) {
   await fs.mkdir(path.dirname(alvo), { recursive: true });
-  if (a.texto != null) await fs.writeFile(alvo, a.texto, { encoding: 'utf8', flag: 'wx' });
+  if ((a.bytes ?? a.texto) != null) await fs.writeFile(alvo, a.bytes ?? a.texto, { encoding: 'utf8', flag: 'wx' });
   else await fs.copyFile(a.de, alvo, constants.COPYFILE_EXCL);
 }
 

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

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

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

@@ -25,10 +25,10 @@ async function limparSobras({ entrega, tmp, antiga }) {
   if ((await tipoDe(tmp)) === 'pasta') await apagar(tmp);
 }
 
-/** Grava um arquivo da entrega na pasta temporária: o texto gerado, ou os mesmos bytes da origem. */
+/** Grava um arquivo da entrega na pasta temporária: os bytes ou o texto gerados, ou os mesmos bytes da origem. */
 async function gravarArquivo(destino, a) {
   await fs.mkdir(path.dirname(destino), { recursive: true });
-  if (a.texto != null) await fs.writeFile(destino, a.texto, 'utf8');
+  if ((a.bytes ?? a.texto) != null) await fs.writeFile(destino, a.bytes ?? a.texto, 'utf8');
   else await fs.copyFile(a.de, destino);
 }
 
@@ -51,7 +51,7 @@ async function trocar({ entrega, tmp, antiga }, passo) {
 /**
  * Refaz `entrega/` do zero e grava, ao lado, o relatório da verificação.
  * @param {string} execucao pasta da execução (`crews/<crew>/output/<run>/`), absoluta
- * @param {object[]} arquivos `{ pasta, nome, texto | de }`
+ * @param {object[]} arquivos `{ pasta, nome, texto | bytes | de }`
  * @param {{ leiame: string, relatorio: string }} textos
  * @returns {Promise<string|null>} null quando gravou tudo; senão, o caminho que não foi gravado
  */