cosmemilton-acbr-node 0.1.1 → 0.1.2

package/dist/types/src/contract-help.d.ts

@@ -0,0 +1,53 @@
+import type { ModelIR, ModelProperty } from './generator.js';
+export interface ContractMetadata {
+    formatVersion: 1;
+    sourceRevision: number;
+    sourceHash: string;
+    contractHash: string;
+    ir: ModelIR;
+}
+export interface FieldDescription {
+    formatVersion: 1;
+    sdkVersion: string;
+    sourceRevision: number;
+    sourceHash: string;
+    contractHash: string;
+    root: string;
+    path: string;
+    kind: ModelProperty['kind'];
+    pascalType: string;
+    typeReference?: string;
+    inputType: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    readonly: boolean;
+    declaredDefault?: string;
+    values?: string[];
+    constraints?: {
+        min?: number;
+        max?: number;
+        scale?: number;
+    };
+    itemType?: string;
+    members?: {
+        name: string;
+        kind: ModelProperty['kind'];
+        pascalType: string;
+        readonly: boolean;
+    }[];
+}
+export declare class FieldHelpError extends Error {
+    readonly code: string;
+    readonly details?: {
+        segment?: string;
+        ownerType?: string;
+        candidates?: string[];
+    } | undefined;
+    constructor(code: string, message: string, details?: {
+        segment?: string;
+        ownerType?: string;
+        candidates?: string[];
+    } | undefined);
+}
+export declare function validateContractMetadata(value: unknown): ContractMetadata;
+export declare function describeField(metadata: ContractMetadata, sdkVersion: string, query: string): FieldDescription;
+export declare function describeInstalledField(query: string, packageRoot: string): Promise<FieldDescription>;
+export declare function formatFieldDescription(description: FieldDescription): string;

package/dist/types/src/generator.d.ts

@@ -82,6 +82,7 @@ export declare function compareContracts(previous: ModelIR | undefined, current:
 };
 export declare function renderModelValidation(): string;
 export declare function renderTypeScript(ir: ModelIR, revision: number, contractHash: string): string;
+export declare function renderContractMetadata(ir: ModelIR, sourceRevision: number, sourceHash: string, contractHash: string): string;
 export declare function renderPascal(ir: ModelIR, revision: number, contractHash: string): string;
 export declare function renderClientIndex(): string;
 export declare function generateModel(options: GenerateOptions): Promise<{
@@ -90,5 +91,6 @@ export declare function generateModel(options: GenerateOptions): Promise<{
     models: number;
     reportPath: string;
     manifestPath: string;
+    metadataPath: string;
 }>;
 export {};

package/dist/types/src/index.d.ts

@@ -2,7 +2,7 @@ import { type OpcoesEmissor, type OpcoesOperacao } from './runtime.js';
 import { type TNFeInput } from '../generated/acbr/models.js';
 export * from './runtime.js';
 export * from '../generated/acbr/models.js';
-export declare function diagnosticarErro(erro: unknown): import("./types.js").DiagnosticoAcbr | Readonly<{
+export declare function diagnosticarErro(erro: unknown): Readonly<{
     codigo: import("./index.js").CodigoValidacaoModelo;
     etapa: "documento";
     campo?: string;
@@ -14,7 +14,7 @@ export declare function diagnosticarErro(erro: unknown): import("./types.js").Di
         etapa: "documento";
         campo?: string;
     }>;
-}>;
+}> | import("./types.js").DiagnosticoAcbr;
 export type OpcoesCriarEmissor = Omit<OpcoesEmissor, 'contrato' | 'validaDocumento'>;
 export declare function criarEmissor(options: OpcoesCriarEmissor): {
     gerarXml(documento: TNFeInput, operacao?: OpcoesOperacao): Promise<import("./types.js").ResultadoFiscal>;

package/docs/API.md

@@ -1,90 +1,90 @@
-# API e protocolo
-
-`criarEmissor` retorna operações assíncronas; cada chamada inicia um processo fiscal isolado. Uma instância processa uma operação por vez, com fila limitada. Emitentes diferentes não compartilham o componente Pascal.
-
-## Configuração
-
-Campos obrigatórios: `cnpj` (14 dígitos), `uf`, `modelo` (55/65), `ambiente` (1 produção, 2 homologação). Certificado A1: `certificado: { pfx: Uint8Array, senha: string }` ou `{ arquivo: string, senha: string }`. NFC-e requer `csc: { id: string, valor: string }` para os recursos que dependem do CSC.
-
-`timeoutMs` tem padrão/máximo de 120.000 ms; `limiteFila` tem padrão 32. `runtimeDirectory` seleciona um runtime próprio cujo contrato deve coincidir com o cliente. Cada operação aceita `{ signal: AbortSignal }` como último argumento. `fechar()` cancela a fila, encerra e aguarda o processo em execução.
-
-Com `limiteFila: 0`, uma operação pode executar e chamadas concorrentes recebem
-`FILA_CHEIA`. Após o `await` dessa operação, a fila já está disponível para a
-próxima chamada; isso também vale quando a operação termina com erro, salvo
-quando o emissor foi fechado ou o encerramento do motor não foi confirmado.
-
-## Operações
-
-| Método | Entrada |
-| --- | --- |
-| `gerarXml` | Objeto TNFe/TNFeInput com nomes ACBr |
-| `assinar`, `validar`, `transmitir` | XML UTF-8 como string |
-| `consultar` | `{ chave, recibo? }` |
-| `cancelar` | `{ chave, protocolo, justificativa }` |
-| `cartaCorrecao` | `{ chave, correcao, sequenciaEvento? }`; modelo 55 |
-| `inutilizar` | `{ ano, serie, numeroInicial, numeroFinal, justificativa }`; ano com 2 dígitos |
-
-A resposta `ResultadoFiscal` contém `sucesso`, `estado`, revisão/hash do contrato e, quando disponíveis, `cStat`, `xMotivo`, `chave`, `protocolo`, `recibo` e `xmlBase64`. `sucesso` deve ser conferido antes de usar o resultado. XML é devolvido em base64 para preservar os bytes UTF-8.
-
-Rejeições fiscais e recibos pendentes são resultados, sem retry automático. Falhas no supervisor lançam `ErroAcbrNode` com `codigo` e `resultadoDesconhecido`. Em falha/timeout de uma operação que pode ter iniciado envio, consulte a situação fiscal antes de decidir uma nova transmissão. O erro de transmissão conserva `xmlBase64` para recuperação.
-
-## Feedback seguro para o usuário
-
-Os resultados incluem `diagnostico`, com `codigo`, `etapa`, `mensagem`, `acao`,
-`statusEnvio` e, quando disponíveis, `campo` e `cStat`. Também estão disponíveis
-os helpers `diagnosticarErro(erro)` e `diagnosticarResultado(resultado, comando)`.
-Use esse resumo nas interfaces e nos logs. Ele não copia XML, identidade fiscal,
-caminhos, senha, `xMotivo`, stderr, stack ou causa bruta.
-
-```ts
-import { TNFe, diagnosticarErro, diagnosticarResultado } from 'cosmemilton-acbr-node';
-
-try {
-  const resultado = await emissor.gerarXml(new TNFe(dados));
-  const d = resultado.diagnostico ?? diagnosticarResultado(resultado, 'gerarXml');
-  mostrarAoUsuario(d); // Apresente mensagem, campo, ação e statusEnvio.
-} catch (erro) {
-  mostrarAoUsuario(diagnosticarErro(erro)); // Não registre o erro bruto.
-}
-```
-
-As validações dos modelos continuam lançando uma subclasse de `TypeError`
-(`ErroValidacaoModelo`). Por exemplo, uma data com fuso em `TNFe.Ide.dEmi`
-informa `DATA_HORA_INVALIDA`, o campo e a orientação de usar a data/hora civil
-da UF em `AAAA-MM-DDTHH:mm:ss`, sem `Z` ou offset. Nenhum valor informado é
-incluído no diagnóstico. Uma chave desconhecida aponta o grupo conhecido,
-evitando registrar chaves que possam conter dados privados.
-
-`statusEnvio` refere-se à operação atual:
-
-| Status | Significado |
-| --- | --- |
-| `nao_enviado` | Etapa local confirmada ou falha comprovadamente anterior ao envio desta operação. Não prova ausência de envios anteriores. |
-| `rejeitado` | Resultado fiscal de rejeição ou denegação; confira `cStat` e a orientação. |
-| `autorizado` | Autorização confirmada com identidade/protocolo; em eventos, a mensagem identifica cancelamento, registro ou inutilização. |
-| `resultado_incerto` | Resultado pendente, evidência incompleta/contraditória ou interrupção após possível envio. Consulte antes de repetir. |
-
-Os campos e os estados anteriores da API permanecem disponíveis. O XML de
-recuperação de `ErroAcbrNode` ainda pode ser lido explicitamente em `xmlBase64`,
-mas não é enumerável; `JSON.stringify(erro)` devolve apenas o diagnóstico
-sanitizado. `cause` contém somente código, etapa e campo conhecidos. Nenhum
-helper retransmite ou altera o resultado fiscal.
-
-O encerramento de um filho fiscal iniciado aguarda `close` por até 1000 ms após
-o pedido de parada. Se `kill` falha ou o filho não confirma o encerramento, a
-operação termina com seu erro original e um aviso adicional em
-`diagnostico.limpeza`, com código `ENCERRAMENTO_MOTOR_NAO_CONFIRMADO` e etapa
-`limpeza`. O supervisor libera somente os pipes e handles desse filho,
-bloqueia a fila e novas operações do emissor e não afirma que o processo
-terminou. Encerre a aplicação antes de iniciar outro motor; se havia envio
-possível, consulte a situação fiscal antes de repetir. Chamadas concorrentes
-de `fechar()` aguardam o mesmo encerramento limitado. O watcher nativo
-acompanha o processo pai e encerra o filho quando o pai termina.
-
-## Processo auxiliar
-
-Protocolo JSONL versão 1 em stdin/stdout. Certificado e senha são enviados pelas pipes, nunca como argumentos. O ambiente herdado é restrito a variáveis de sistema; stderr bruto não é apresentado como erro público. Limites de mensagem, timeout, checks de hash e validações de identidade protegem a comunicação. O processo acompanha o PID do pai e termina quando o pai encerra.
-
-Cada pedido tem `id`, `versao`, `sourceRevision`, `contractHash`, `comando`, `config` e parâmetros da operação. Antes de enviar uma operação com efeitos fiscais, o motor escreve `{ tipo: "envioIniciado", id }`. A resposta final precisa repetir identidade e contrato. O supervisor aguarda o fechamento do processo antes de liberar a próxima operação.
-
-TLS usa OpenSSL com verificação de cadeia, validade, finalidade e hostname antes de enviar bytes de aplicação. No Linux usa as CAs do sistema; no Windows exporta raízes públicas confiáveis para um bundle temporário. Esta versão não implementa consulta de revogação CRL/OCSP.
+# API e protocolo
+
+`criarEmissor` retorna operações assíncronas; cada chamada inicia um processo fiscal isolado. Uma instância processa uma operação por vez, com fila limitada. Emitentes diferentes não compartilham o componente Pascal.
+
+## Configuração
+
+Campos obrigatórios: `cnpj` (14 dígitos), `uf`, `modelo` (55/65), `ambiente` (1 produção, 2 homologação). Certificado A1: `certificado: { pfx: Uint8Array, senha: string }` ou `{ arquivo: string, senha: string }`. NFC-e requer `csc: { id: string, valor: string }` para os recursos que dependem do CSC.
+
+`timeoutMs` tem padrão/máximo de 120.000 ms; `limiteFila` tem padrão 32. `runtimeDirectory` seleciona um runtime próprio cujo contrato deve coincidir com o cliente. Cada operação aceita `{ signal: AbortSignal }` como último argumento. `fechar()` cancela a fila, encerra e aguarda o processo em execução.
+
+Com `limiteFila: 0`, uma operação pode executar e chamadas concorrentes recebem
+`FILA_CHEIA`. Após o `await` dessa operação, a fila já está disponível para a
+próxima chamada; isso também vale quando a operação termina com erro, salvo
+quando o emissor foi fechado ou o encerramento do motor não foi confirmado.
+
+## Operações
+
+| Método | Entrada |
+| --- | --- |
+| `gerarXml` | Objeto TNFe/TNFeInput com nomes ACBr |
+| `assinar`, `validar`, `transmitir` | XML UTF-8 como string |
+| `consultar` | `{ chave, recibo? }` |
+| `cancelar` | `{ chave, protocolo, justificativa }` |
+| `cartaCorrecao` | `{ chave, correcao, sequenciaEvento? }`; modelo 55 |
+| `inutilizar` | `{ ano, serie, numeroInicial, numeroFinal, justificativa }`; ano com 2 dígitos |
+
+A resposta `ResultadoFiscal` contém `sucesso`, `estado`, revisão/hash do contrato e, quando disponíveis, `cStat`, `xMotivo`, `chave`, `protocolo`, `recibo` e `xmlBase64`. `sucesso` deve ser conferido antes de usar o resultado. XML é devolvido em base64 para preservar os bytes UTF-8.
+
+Rejeições fiscais e recibos pendentes são resultados, sem retry automático. Falhas no supervisor lançam `ErroAcbrNode` com `codigo` e `resultadoDesconhecido`. Em falha/timeout de uma operação que pode ter iniciado envio, consulte a situação fiscal antes de decidir uma nova transmissão. O erro de transmissão conserva `xmlBase64` para recuperação.
+
+## Feedback seguro para o usuário
+
+Os resultados incluem `diagnostico`, com `codigo`, `etapa`, `mensagem`, `acao`,
+`statusEnvio` e, quando disponíveis, `campo` e `cStat`. Também estão disponíveis
+os helpers `diagnosticarErro(erro)` e `diagnosticarResultado(resultado, comando)`.
+Use esse resumo nas interfaces e nos logs. Ele não copia XML, identidade fiscal,
+caminhos, senha, `xMotivo`, stderr, stack ou causa bruta.
+
+```ts
+import { TNFe, diagnosticarErro, diagnosticarResultado } from 'cosmemilton-acbr-node';
+
+try {
+  const resultado = await emissor.gerarXml(new TNFe(dados));
+  const d = resultado.diagnostico ?? diagnosticarResultado(resultado, 'gerarXml');
+  mostrarAoUsuario(d); // Apresente mensagem, campo, ação e statusEnvio.
+} catch (erro) {
+  mostrarAoUsuario(diagnosticarErro(erro)); // Não registre o erro bruto.
+}
+```
+
+As validações dos modelos continuam lançando uma subclasse de `TypeError`
+(`ErroValidacaoModelo`). Por exemplo, uma data com fuso em `TNFe.Ide.dEmi`
+informa `DATA_HORA_INVALIDA`, o campo e a orientação de usar a data/hora civil
+da UF em `AAAA-MM-DDTHH:mm:ss`, sem `Z` ou offset. Nenhum valor informado é
+incluído no diagnóstico. Uma chave desconhecida aponta o grupo conhecido,
+evitando registrar chaves que possam conter dados privados.
+
+`statusEnvio` refere-se à operação atual:
+
+| Status | Significado |
+| --- | --- |
+| `nao_enviado` | Etapa local confirmada ou falha comprovadamente anterior ao envio desta operação. Não prova ausência de envios anteriores. |
+| `rejeitado` | Resultado fiscal de rejeição ou denegação; confira `cStat` e a orientação. |
+| `autorizado` | Autorização confirmada com identidade/protocolo; em eventos, a mensagem identifica cancelamento, registro ou inutilização. |
+| `resultado_incerto` | Resultado pendente, evidência incompleta/contraditória ou interrupção após possível envio. Consulte antes de repetir. |
+
+Os campos e os estados anteriores da API permanecem disponíveis. O XML de
+recuperação de `ErroAcbrNode` ainda pode ser lido explicitamente em `xmlBase64`,
+mas não é enumerável; `JSON.stringify(erro)` devolve apenas o diagnóstico
+sanitizado. `cause` contém somente código, etapa e campo conhecidos. Nenhum
+helper retransmite ou altera o resultado fiscal.
+
+O encerramento de um filho fiscal iniciado aguarda `close` por até 1000 ms após
+o pedido de parada. Se `kill` falha ou o filho não confirma o encerramento, a
+operação termina com seu erro original e um aviso adicional em
+`diagnostico.limpeza`, com código `ENCERRAMENTO_MOTOR_NAO_CONFIRMADO` e etapa
+`limpeza`. O supervisor libera somente os pipes e handles desse filho,
+bloqueia a fila e novas operações do emissor e não afirma que o processo
+terminou. Encerre a aplicação antes de iniciar outro motor; se havia envio
+possível, consulte a situação fiscal antes de repetir. Chamadas concorrentes
+de `fechar()` aguardam o mesmo encerramento limitado. O watcher nativo
+acompanha o processo pai e encerra o filho quando o pai termina.
+
+## Processo auxiliar
+
+Protocolo JSONL versão 1 em stdin/stdout. Certificado e senha são enviados pelas pipes, nunca como argumentos. O ambiente herdado é restrito a variáveis de sistema; stderr bruto não é apresentado como erro público. Limites de mensagem, timeout, checks de hash e validações de identidade protegem a comunicação. O processo acompanha o PID do pai e termina quando o pai encerra.
+
+Cada pedido tem `id`, `versao`, `sourceRevision`, `contractHash`, `comando`, `config` e parâmetros da operação. Antes de enviar uma operação com efeitos fiscais, o motor escreve `{ tipo: "envioIniciado", id }`. A resposta final precisa repetir identidade e contrato. O supervisor aguarda o fechamento do processo antes de liberar a próxima operação.
+
+TLS usa OpenSSL com verificação de cadeia, validade, finalidade e hostname antes de enviar bytes de aplicação. No Linux usa as CAs do sistema; no Windows exporta raízes públicas confiáveis para um bundle temporário. Esta versão não implementa consulta de revogação CRL/OCSP.

package/docs/CLI.md

@@ -1,32 +1,52 @@
-# Fontes, contrato e build
-
-`init` cria a configuração e copia os fontes do motor e extractor distribuídos no pacote para o projeto do consumidor, preservando arquivos existentes. O CLI usa `acbr.config.json`. Todos os caminhos relativos são resolvidos pelo diretório desse arquivo, independentemente do diretório atual do terminal. Campos desconhecidos, revisão inválida ou outra origem SVN são rejeitados.
-
-```sh
-acbr-node init
-acbr-node source update
-acbr-node generate
-acbr-node build
-acbr-node check
-acbr-node doctor
-```
-
-`source update` é a única operação que busca alterações do SVN. Primeiro resolve `HEAD` para um número, exporta `Fontes`, schemas NF-e e licença para uma área temporária e registra a revisão e SHA256 de cada arquivo em `acbr.lock.json`. Se já houver fontes, precisa de um lock válido e recusa arquivos alterados, adicionados ou removidos. A geração, compilação e execução não atualizam fontes automaticamente.
-
-`source update` sem `--revision` consulta a revisão mais recente (`HEAD`), mesmo quando a configuração registra uma revisão anterior. `source update --revision 48590` seleciona explicitamente uma revisão. Após download e lock bem-sucedidos, o CLI persiste a revisão numérica resolvida na configuração, preservando os caminhos e demais campos. Falhas restauram fontes e lock; nenhuma atualização acontece na execução normal. Um export previamente obtido e conferido pelo operador pode ser registrado com `source lock --revision 48590`; esse comando confia na origem declarada pelo operador e calcula os hashes locais, sem comparar o conteúdo com o SVN remoto.
-
-`generate` recria os tipos em `generated/acbr/models.ts`, o mapper Pascal em `native/generated/AcbrModels.pas` e os manifestos/relatórios em `.acbr/generated`. Revise o relatório após cada atualização para detectar campos novos, removidos, enums e partes que o gerador não suporta.
-
-`build` confere fontes/contrato antes de invocar o Free Pascal. Usa os defines `NOGUI` e `NOREPORT`, unidades Lazarus sem interface gráfica, ACBr original e mapper gerado. Linux x64 e Windows x64 são os alvos iniciais. A compilação precisa ocorrer no sistema do alvo; não há cross-compilation implícita.
-
-No Linux, instale Free Pascal 3.2.2, Lazarus 3.0, SVN, OpenSSL 3, libxml2, tar/gzip e certificados CA do sistema. `native.lazarusRoot` ou `LAZARUS_ROOT` podem indicar outra instalação. O staging copia OpenSSL/libxml2 e suas dependências transitivas como bibliotecas dinâmicas com suas licenças e origem/versionamento dos pacotes fonte. Inclui o provider legacy e configuração de providers OpenSSL. glibc e o loader permanecem requisitos do sistema. O Linux usa glibc: o runtime não equivale a um binário portátil para qualquer distribuição ou Alpine.
-
-No Windows, configure `native.lazarusRoot`, `native.fpc`, `native.providerFiles` (incluindo `legacy.dll`) e `native.libraryFiles` para as DLLs x64 de TLS/XML. Cada DLL exige um arquivo de licença adjacente `<DLL>.LICENSE`; `<DLL>.SOURCE.json` registra opcionalmente origem e versão do código correspondente e é incluído na proveniência do runtime. As dependências também podem ser compiladas no WSL com MinGW, conforme [Dependências nativas](DEPENDENCIAS-NATIVAS.md). O motor Pascal é compilado no Windows pelo CLI; a compilação não substitui a homologação fiscal. A [receita de CI](CI.md) documenta instalação oficial gratuita, `FPC_ROOT`/`LAZARUS_ROOT` e criação de um `fpc.cfg` exclusivo com `PPC_CONFIG_PATH`, sem alterar a instalação do compilador.
-
-No Windows, execute comandos `npm` em uma pasta local, por exemplo `C:\Projetos\MinhaAplicacao`. O launcher `npm.cmd` usa `cmd.exe`, que não mantém um caminho UNC como diretório atual. Para trabalhar com um checkout WSL acessado por `\\wsl.localhost\...`, execute a CLI por `node caminho\dist\cli.js` e, quando necessário, invoque `npm-cli.js` diretamente por Node, indicando o caminho da instalação. Na compilação Pascal, fontes em uma pasta Windows local evitam o custo de leitura por UNC; `source.directory` pode apontar para essa cópia e o lock confere os mesmos hashes.
-
-O runtime fica em `.acbr/runtime/<platform>-<arch>`, contendo executável, bibliotecas dinâmicas, schemas, serviços NF-e, licenças, fontes correspondentes e `manifest.json`. O manifesto registra revisão ACBr, contrato, plataforma e SHA256 de cada arquivo. `check` verifica todos esses vínculos e arquivos e depois inicia o motor real em quatro probes locais: gera uma NF-e55 sintética para conferir mapper/chave/UTF-8, valida uma fixture XML assinada com certificado público sintético e recusa XML malformado e DTD/entidade externa. O smoke não recebe PFX, chave privada ou senha e não transmite documentos; `--json` inclui `offlineChecks`. A fixture assinada fica embutida no CLI, pois o schema exige `Signature` e o XML gerado sem A1 ainda não é assinado. O builder confere SHA256 dos três arquivos gerados antes e depois da compilação; uma alteração de mapper/helper invalida o build mesmo quando o hash do contrato permanece igual. O staging inclui notices FPC (GPL do compilador, LGPL e exceção da RTL), Lazarus e das bibliotecas dinâmicas, além da proveniência das cópias usadas. `doctor` informa ferramentas e dependências encontradas; ele não instala ferramentas nem transmite documentos.
-
-Atualizações concorrentes são recusadas com `acbr.lock.json.operation`. Se um processo encerrar abruptamente, confira o PID registrado antes de remover o marcador. Uma alteração de revisão durante a compilação invalida o resultado. O log FPC completo fica em `.acbr/build.log`.
-
-Use `--config caminho` para escolher a configuração e `--json` para obter saída estruturada. Nunca inclua senhas ou certificados nesse arquivo de build: a API recebe essas credenciais separadamente em memória.
+# Fontes, contrato e build
+
+## Help de tipos e campos — implementação de desenvolvimento
+
+O help TAG faz parte da release 0.1.2. A documentação pública só anuncia disponibilidade após a confirmação dessa versão no registry npm.
+
+```sh
+node dist/cli.js help TAG Ide.tpNF
+node dist/cli.js help TAG 'Det[].Imposto.PIS.CST' --json
+node dist/cli.js help TAG 'TNFe.Det[0].Prod.DI[].adi[2].nAdicao' --json
+```
+
+`Ide.tpNF` resolve para `TTipoNFe` e apresenta `tnEntrada` e `tnSaida`. O caminho PIS resolve para `TCSTPis`, com seus valores textuais, incluindo `pis99`. Os valores são obtidos do contrato gerado; não há catálogo de enums mantido manualmente.
+
+O prefixo `TNFe.` é opcional. Os nomes dos campos respeitam maiúsculas e minúsculas; `TAG` aceita ambas. `[]` consulta o tipo do elemento de uma coleção. Um índice não negativo, como `[0]`, é normalizado para `[]`: a consulta não lê uma nota nem confere a quantidade de itens. Um nome curto só é aceito quando identifica um caminho único; `CST` retorna `CAMPO_AMBIGUO` com os caminhos possíveis. `Det.Imposto` pede um seletor de coleção, enquanto `Ide[]` é recusado por não ser coleção.
+
+O help lê somente `dist/contract.json`, `package.json` e `acbr.lock.json` da própria instalação. Não consulta configuração do consumidor, runtime, certificado, SVN ou rede e funciona sem dependências opcionais. `--config` e `--revision` não se aplicam a esse comando. Saída JSON contém versão do SDK, revisão ACBr, hashes, caminho canônico, tipo, referências, valores, limites do tipo e indicação de somente leitura. Erros JSON vão para `stderr`, com código de saída 1; uma consulta válida termina com 0.
+
+Os caminhos pertencem ao modelo de entrada do SDK, não são XPath/XML. Por exemplo, o modelo usa `Ide.dEmi`; `Ide.dhEmi` é inexistente. `declaredDefault` é a declaração Pascal, não uma garantia sobre o construtor nativo. Limites primitivos, enums e campos opcionais do TypeScript não substituem regras fiscais, códigos XML, obrigatoriedade ou orientação tributária.
+
+`generate` também emite `generated/acbr/contract.json` a partir do mesmo IR usado pelo validador. O build confere o hash e o lock e distribui esses metadados em `dist/contract.json`, separados dos três arquivos gerados que vinculam o motor.
+
+`init` cria a configuração e copia os fontes do motor e extractor distribuídos no pacote para o projeto do consumidor, preservando arquivos existentes. O CLI usa `acbr.config.json`. Todos os caminhos relativos são resolvidos pelo diretório desse arquivo, independentemente do diretório atual do terminal. Campos desconhecidos, revisão inválida ou outra origem SVN são rejeitados.
+
+```sh
+acbr-node init
+acbr-node source update
+acbr-node generate
+acbr-node build
+acbr-node check
+acbr-node doctor
+```
+
+`source update` é a única operação que busca alterações do SVN. Primeiro resolve `HEAD` para um número, exporta `Fontes`, schemas NF-e e licença para uma área temporária e registra a revisão e SHA256 de cada arquivo em `acbr.lock.json`. Se já houver fontes, precisa de um lock válido e recusa arquivos alterados, adicionados ou removidos. A geração, compilação e execução não atualizam fontes automaticamente.
+
+`source update` sem `--revision` consulta a revisão mais recente (`HEAD`), mesmo quando a configuração registra uma revisão anterior. `source update --revision 48590` seleciona explicitamente uma revisão. Após download e lock bem-sucedidos, o CLI persiste a revisão numérica resolvida na configuração, preservando os caminhos e demais campos. Falhas restauram fontes e lock; nenhuma atualização acontece na execução normal. Um export previamente obtido e conferido pelo operador pode ser registrado com `source lock --revision 48590`; esse comando confia na origem declarada pelo operador e calcula os hashes locais, sem comparar o conteúdo com o SVN remoto.
+
+`generate` recria os tipos em `generated/acbr/models.ts`, o mapper Pascal em `native/generated/AcbrModels.pas` e os manifestos/relatórios em `.acbr/generated`. Revise o relatório após cada atualização para detectar campos novos, removidos, enums e partes que o gerador não suporta.
+
+`build` confere fontes/contrato antes de invocar o Free Pascal. Usa os defines `NOGUI` e `NOREPORT`, unidades Lazarus sem interface gráfica, ACBr original e mapper gerado. Linux x64 e Windows x64 são os alvos iniciais. A compilação precisa ocorrer no sistema do alvo; não há cross-compilation implícita.
+
+No Linux, instale Free Pascal 3.2.2, Lazarus 3.0, SVN, OpenSSL 3, libxml2, tar/gzip e certificados CA do sistema. `native.lazarusRoot` ou `LAZARUS_ROOT` podem indicar outra instalação. O staging copia OpenSSL/libxml2 e suas dependências transitivas como bibliotecas dinâmicas com suas licenças e origem/versionamento dos pacotes fonte. Inclui o provider legacy e configuração de providers OpenSSL. glibc e o loader permanecem requisitos do sistema. O Linux usa glibc: o runtime não equivale a um binário portátil para qualquer distribuição ou Alpine.
+
+No Windows, configure `native.lazarusRoot`, `native.fpc`, `native.providerFiles` (incluindo `legacy.dll`) e `native.libraryFiles` para as DLLs x64 de TLS/XML. Cada DLL exige um arquivo de licença adjacente `<DLL>.LICENSE`; `<DLL>.SOURCE.json` registra opcionalmente origem e versão do código correspondente e é incluído na proveniência do runtime. As dependências também podem ser compiladas no WSL com MinGW, conforme [Dependências nativas](DEPENDENCIAS-NATIVAS.md). O motor Pascal é compilado no Windows pelo CLI; a compilação não substitui a homologação fiscal. A [receita de CI](CI.md) documenta instalação oficial gratuita, `FPC_ROOT`/`LAZARUS_ROOT` e criação de um `fpc.cfg` exclusivo com `PPC_CONFIG_PATH`, sem alterar a instalação do compilador.
+
+No Windows, execute comandos `npm` em uma pasta local, por exemplo `C:\Projetos\MinhaAplicacao`. O launcher `npm.cmd` usa `cmd.exe`, que não mantém um caminho UNC como diretório atual. Para trabalhar com um checkout WSL acessado por `\\wsl.localhost\...`, execute a CLI por `node caminho\dist\cli.js` e, quando necessário, invoque `npm-cli.js` diretamente por Node, indicando o caminho da instalação. Na compilação Pascal, fontes em uma pasta Windows local evitam o custo de leitura por UNC; `source.directory` pode apontar para essa cópia e o lock confere os mesmos hashes.
+
+O runtime fica em `.acbr/runtime/<platform>-<arch>`, contendo executável, bibliotecas dinâmicas, schemas, serviços NF-e, licenças, fontes correspondentes e `manifest.json`. O manifesto registra revisão ACBr, contrato, plataforma e SHA256 de cada arquivo. `check` verifica todos esses vínculos e arquivos e depois inicia o motor real em quatro probes locais: gera uma NF-e55 sintética para conferir mapper/chave/UTF-8, valida uma fixture XML assinada com certificado público sintético e recusa XML malformado e DTD/entidade externa. O smoke não recebe PFX, chave privada ou senha e não transmite documentos; `--json` inclui `offlineChecks`. A fixture assinada fica embutida no CLI, pois o schema exige `Signature` e o XML gerado sem A1 ainda não é assinado. O builder confere SHA256 dos três arquivos gerados antes e depois da compilação; uma alteração de mapper/helper invalida o build mesmo quando o hash do contrato permanece igual. O staging inclui notices FPC (GPL do compilador, LGPL e exceção da RTL), Lazarus e das bibliotecas dinâmicas, além da proveniência das cópias usadas. `doctor` informa ferramentas e dependências encontradas; ele não instala ferramentas nem transmite documentos.
+
+Atualizações concorrentes são recusadas com `acbr.lock.json.operation`. Se um processo encerrar abruptamente, confira o PID registrado antes de remover o marcador. Uma alteração de revisão durante a compilação invalida o resultado. O log FPC completo fica em `.acbr/build.log`.
+
+Use `--config caminho` para escolher a configuração e `--json` para obter saída estruturada. Nunca inclua senhas ou certificados nesse arquivo de build: a API recebe essas credenciais separadamente em memória.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cosmemilton-acbr-node",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "NF-e/NFC-e com ACBr Free Pascal, cliente TypeScript gerado e CLI SVN",
   "license": "LGPL-2.1-or-later",
   "type": "module",
@@ -26,6 +26,7 @@
   "files": [
     "dist",
     "native",
+    "native/generated/AcbrModels.pas",
     "tools",
     "LICENSE",
     "NOTICE",
@@ -50,11 +51,12 @@
     "acbr": "tsx src/cli.ts",
     "pack:runtimes": "node scripts/pack-runtimes.mjs",
     "release:prepare": "node scripts/publish-artifacts.mjs",
-    "test:package": "node tests/package-install.mjs"
+    "test:package": "node tests/package-install.mjs",
+    "test:help-installed": "node tests/cli-help-installed.mjs"
   },
   "optionalDependencies": {
-    "cosmemilton-acbr-node-linux-x64": "0.1.1",
-    "cosmemilton-acbr-node-win32-x64": "0.1.1"
+    "cosmemilton-acbr-node-linux-x64": "0.1.2",
+    "cosmemilton-acbr-node-win32-x64": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",