Repassar um projeto de livro: a pasta que outra pessoa consegue refazer sozinha

Chegamos a ter sete scripts de livro que divergiam entre o servidor de trabalho e o repositório, e em cada arquivo a direção era diferente. Um estava mais novo em um lado, outro no outro. Em um episódio anterior, uma cópia local sobrescreveu um patch do servidor e derrubou uma etapa.

Um projeto assim funciona enquanto quem o montou está por perto. No dia em que outra pessoa pega, ela precisa adivinhar qual cópia vale.

Este artigo diz o que entregar para outra pessoa refazer o livro sozinha. Traz o teste que prova que o build é reproduzível e as armadilhas de cópia e de segredo.

O que entra no pacote de repasse

Sete itens, e cada um responde a uma pergunta que o diagramador novo faria no primeiro dia.

1. O procedimento

O mapa em uma tela está no mapa da esteira, com e sem IA. O comando que diz em que passo cada cliente está lê o disco e não guarda estado, de propósito. Um checklist mantido à mão diverge do mundo em duas semanas: alguém faz o passo e esquece de marcar, ou marca e não faz. Quem garante a execução são as guardas, que abortam o arquivo. O mapa é o mapa, e a guarda é a cancela.

2 e 3. A pasta e o índice

A regra de dois lugares: o repositório guarda o pensamento, e a pasta de insumo guarda o material bruto (transcrições, áudios, arquivos que o autor mandou). Procurar em um lugar só já produziu seis declarações erradas de "AUSENTE": as gravações estavam no outro lado.

O índice é uma tabela de três colunas, e nada além disso:

| tipo | onde | nota |
|---|---|---|
| gate-de-fonte | 00-CONFIRMADO-x-SEM-FONTE.md | |
| transcricao | FORA: pasta-de-insumo/transcricoes | não versionada |
| manuscrito | AUSENTE | perdido em uma migração; refazer a partir do PDF |

A coluna "onde" tem três formas, e a diferença entre elas é o valor do índice. Um caminho significa que o arquivo está na pasta. FORA: <onde> significa que existe, fora do repositório, e o endereço é obrigatório. AUSENTE significa que não existe em lugar nenhum, e a nota passa a ser obrigatória, porque é o registro de uma perda.

A regra mais barata do padrão: nenhum arquivo se move, nenhum se renomeia. O índice só diz o que é cada um. Um projeto de migração em dezenas de clientes é o tipo de plano que nunca fecha.

4. Versões e fontes

Entregue a matriz de versões e a pasta de fontes do projeto, com o texto da licença de cada uma. A pasta de fontes entra no comando de compilação, para que o livro abra igual em outra máquina. A instalação do ambiente está em instalar o ambiente.

5. Uma cópia canônica por script

A regra que adotamos: a cópia canônica de cada script vive no repositório versionado. A reconciliação é feita arquivo a arquivo. Revise o que mudou. Funda à mão quando cada lado tem linhas próprias. Teste um caso conhecido antes e depois, e guarde um backup datado. Só depois de aprovada, a cópia do outro lado vira um atalho de uma linha que chama a canônica.

Descartamos duas saídas fáceis. Copiar um lado sobre o outro perderia o código mais novo de um dos lados. Criar atalhos em massa é arriscado quando há centenas de scripts e serviços que dependem deles.

Uma lição que veio depois. Vinte scripts de pré-impressão e publicação só existiam em uma cópia no servidor, sem histórico. Um projeto que depende deles não é repassável. Primeiro, eles precisam estar em cópia versionada. Foi o que fizemos, e é a primeira coisa a conferir no seu.

Dois cuidados do pacote:

• Script de um cliente só. Um script que tem o nome de um cliente fixo no código precisa ser marcado como tal. Quem herdar não pode tratá-lo como genérico.
• Segredos. Chaves e senhas escritas em arquivos de texto, ou como valor padrão no código, viajam junto com o projeto. Varra o projeto por segredos antes de repassar, e rotacione qualquer um que achar. O histórico do repositório guarda o que já foi escrito, então só a rotação resolve.

6. O comando de regeneração e o SHA-256

Repassar é entregar o comando que refaz o miolo e a prova de que refez igual. Em Typst, o PDF leva a data de criação, e por isso dois builds do mesmo arquivo dão códigos diferentes. Testamos: sem controle, os dois SHA-256 foram diferentes. Fixando a data pela variável SOURCE_DATE_EPOCH, os dois builds saíram idênticos.

#!/bin/bash
# Refaz o miolo do zero e mostra o SHA-256: duas rodadas devem dar o mesmo código.
set -e
export SOURCE_DATE_EPOCH=1700000000
typst compile --font-path fontes --input grafica=1 livro.typ miolo-a.pdf
typst compile --font-path fontes --input grafica=1 livro.typ miolo-b.pdf
sha256sum miolo-a.pdf miolo-b.pdf
[ "$(sha256sum < miolo-a.pdf)" = "$(sha256sum < miolo-b.pdf)" ] && echo "IGUAIS: o build é reproduzível" || { echo "DIFERENTES"; exit 1; }

No nosso teste, a saída terminou com IGUAIS: o build é reproduzível. O código de cada arquivo fica registrado na especificação. Ele responde à pergunta: "o arquivo que a gráfica imprimiu é o mesmo que nós aprovamos?".

Este script fecha o pacote, com o SHA-256 e as medidas lidas do próprio PDF:

#!/bin/bash
# Fecha o pacote para a gráfica: lista os arquivos com SHA-256 e as medidas lidas do próprio PDF.
# Uso: bash hash_pacote.sh miolo.pdf capa.pdf > 00-ESPECIFICACAO-medidas.txt
for f in "$@"; do
  echo "arquivo: $f"
  echo "  sha256: $(sha256sum "$f" | cut -d' ' -f1)"
  pdfinfo -box "$f" 2>/dev/null | grep -E "^(Pages|Page size|TrimBox|BleedBox)" | sed 's/^/  /'
done

bash hash_pacote.sh miolo.pdf capa.pdf > medidas.txt

7. A especificação da gráfica

O arquivo de especificação é o documento que se manda junto com os arquivos, para a gráfica não precisar perguntar. Os blocos:

Campo ainda não decidido entra como "a definir", nunca em branco. Em branco parece esquecimento, e alguém preenche por conta própria. Cada livro tem a pasta desde o início, com um campo de situação: miolo fechado (imprime como está), em produção (versão de trabalho, que será substituída) ou publicado (a edição que está no ar).

Passo a passo do repasse

1. Confira se todo script citado existe em cópia versionada.
2. Varra o projeto por segredos.
3. Escreva o índice com caminho, FORA: ou AUSENTE em cada linha.
4. Entregue a matriz de versões e as fontes com a licença.
5. Escreva o comando de regeneração e rode duas vezes: os códigos precisam ser iguais.
6. Gere a especificação com as medidas lidas do PDF e os códigos.
7. Peça à pessoa nova que refaça um passo sem ajuda, e anote onde ela travou. Cada trava é uma correção no pacote.

O erro que custa caro

Repassar o que você sabe, e não o que está escrito. A pessoa nova não tem como perguntar à sua memória. O segundo erro é entregar duas cópias de um script sem dizer qual vale.

Quando NÃO usar

Para um livro único, feito por uma pessoa que continua no projeto, o pacote inteiro é exagero. Bastam o comando de regeneração e os códigos. O pacote completo compensa quando o trabalho muda de mãos, ou quando há vários livros na mesma esteira.

Alternativa sem o nosso ambiente

Uma pasta com os arquivos, o índice em uma tabela e o comando de regeneração em um arquivo de texto cumprem tudo. O controle de versão do projeto pode ser qualquer um, desde que cada script tenha uma cópia canônica.

O que o Claude faz hoje, e como fazer sem ele

Hoje o Claude lê o disco, diz em que passo o livro está, monta o índice e roda as guardas. Sem ele, o mapa e o índice são tabelas que uma pessoa mantém, e os scripts do artigo cumprem o resto.

Onde entra na operação

O repasse atravessa todos os passos do procedimento. O desenho da esteira está em Como produzimos o miolo de um livro profissional sem InDesign. O uso sem IA está em rodar tudo sem o Claude. As conferências que cada passo exige estão no checklist de preflight.

Baixe, para guardar: mapa da esteira de 17 passos, com e sem IA (PDF).

Versões usadas neste artigo: veja a matriz de versões.