Usar uma revisão própria do ACBr

Este guia é para quem precisa gerar modelos e motor a partir de outra revisão dos fontes públicos do ACBr. Para consumir o pacote pronto, basta instalar pelo npm; este fluxo é opcional.

Atualizar fontes pode mudar campos, enums e contratos. Cliente TypeScript e motor precisam ser gerados da mesma revisão e distribuídos juntos.

Ferramentas

No Linux, o fluxo de referência usa Ubuntu 24.04, Free Pascal 3.2.2, Lazarus 3.0, SVN, OpenSSL 3, libxml2, tar/gzip e CAs do sistema.

No Windows, instale Free Pascal/Lazarus e SVN, configure os caminhos do compilador e bibliotecas x64. O motor deve ser compilado no sistema do alvo; não há cross-compilation automática.

As receitas completas de CI e dependências Windows estão no repositório principal.

1. Inicialize em uma pasta da aplicação

Após instalar o SDK:

npx acbr-node init --revision 48590

O comando cria acbr.config.json e copia fontes do motor/extrator. Arquivos existentes são preservados; uma colisão divergente é recusada. A revisão 48590 é a referência da versão 0.1.0; escolha outra revisão explicitamente quando for sua intenção.

2. Obtenha os fontes oficiais

npx acbr-node source update --revision 48590

Esse é o comando que acessa o SVN oficial. Ele registra revisão numérica e hashes em acbr.lock.json. Geração, compilação e execução normal não atualizam fontes automaticamente.

Sem --revision, source update procura HEAD, mesmo que a configuração tenha uma revisão anterior. Para reproduzir uma geração, sempre informe a revisão desejada.

Se os fontes locais já foram alterados, adicionados ou removidos em relação ao lock, a atualização é recusada. Preserve e entenda suas alterações antes de trocar o snapshot.

3. Gere e revise o contrato

npx acbr-node generate

Principais saídas:

Arquivo	Uso
generated/acbr/models.ts	Tipos e modelos TypeScript
generated/acbr/index.ts	Fábrica vinculada ao contrato gerado
native/generated/AcbrModels.pas	Mapper do motor
.acbr/generated/manifest.json	Contrato e vínculo dos arquivos gerados
.acbr/generated/changes.json	Mudanças de tipos para revisão

Revise o relatório antes de adaptar sua aplicação. Tipos desconhecidos interrompem a geração; não são descartados silenciosamente. Remoções e mudanças de campos podem exigir ajustes e versionamento do adaptador.

4. Compile no alvo

npx acbr-node build
npx acbr-node check
npx acbr-node doctor

build cria o runtime em .acbr/runtime/<platform>-<arch>, com executável, dependências, schemas, serviços, licenças, fontes e manifesto. O log completo do compilador fica em .acbr/build.log.

check confere integridade e executa quatro verificações locais no motor: gera XML55 sintético, valida uma fixture assinada com certificado público sintético e recusa XML malformado e DTD/entidade externa. Não transmite documentos nem precisa de certificado privado.

doctor informa ferramentas e dependências; não instala nada e não transmite documentos.

5. Use o cliente que você gerou

Depois de compilar os arquivos TypeScript da sua aplicação, importe a fábrica local e indique o runtime correspondente:

import { criarEmissor } from './generated/acbr/index.js';

const emissor = criarEmissor({
  cnpj: '11222333000181',
  uf: 'CE',
  modelo: 55,
  ambiente: 2,
  runtimeDirectory: './.acbr/runtime/linux-x64'
});

No Windows, o diretório padrão é .acbr/runtime/win32-x64. Para uma configuração variável, prefira calcular um caminho absoluto. Importe seus modelos de ./generated/acbr/models.js, mantendo o cliente e motor da mesma geração.

Não misture a fábrica do pacote principal com um motor de contrato diferente. A execução recusa esse vínculo.

Configuração e cuidados

Os caminhos relativos de acbr.config.json são resolvidos pelo diretório do arquivo, independente da pasta do terminal. Use --config caminho para escolher outro arquivo e --json para saída estruturada.

Nunca inclua certificado ou senha nesse arquivo de build. Essas credenciais pertencem à configuração do emissor, em memória.

source lock --revision N registra um export local que você obteve e conferiu. Ele confia na origem declarada pelo operador e calcula os hashes; não compara o conteúdo com o SVN remoto.

Operações concorrentes são recusadas por um marcador acbr.lock.json.operation. Após uma interrupção abrupta, confira o PID registrado antes de remover o marcador. Leia a referência completa da CLI.