fluigcli deploy — release por manifesto

O comando executa um plano de release descrito em um arquivo JSON. O plano lista os passos na ordem em que eles devem rodar. O arquivo fica versionado no repositório, junto com o código que ele publica.

Este comando substitui o roteiro de deploy escrito à mão. Um documento com "rode este SQL, publique estes datasets, depois a widget" vira algo executável e auditável.

fluigcli deploy --plan release.json --dry-run    # valida tudo, sem escrever
fluigcli deploy --plan release.json --server homolog
fluigcli deploy --plan release.json --from 3     # retoma do passo 3

O plano

O formato é JSON. O projeto não usa YAML, e YAML exigiria uma dependência nova.

{
  "server": "producao",
  "steps": [
    {"name": "diagnóstico de permissões", "db": "sql/001_check.sql"},
    {"dataset": "datasets/ds_jud_agenda.js", "new": true},
    {"dataset": "datasets/ds_jud_processos.js"},
    {"event": "events/displayCustomThemes.js"},
    {"mechanism": "mechanisms/mec_gestor_area.js"},
    {"widget": "processos_judiciais", "build": true},
    {"workflow": "Compras"},
    {"form": "forms/frm_pedido"}
  ]
}

• server — o servidor alvo do plano. A opção --server da linha de comando vence este valor.
• steps — a lista ordenada. Cada passo tem exatamente uma chave de tipo.

Chave de tipo	Alvo	Opções
dataset	arquivo .js	new (cria o dataset), description
event	arquivo .js	—
mechanism	arquivo .js	description
form	pasta forms/<pasta>	new, formName, documentId, parentId, datasetName, cardDescription, persistenceType, version
widget	código do widget	build (roda npm run build), force
layout	código do layout (wcm/layout/<código>)	force
workflow	prefixo local dos scripts	processId, noRelease
db	arquivo .sql	— (só leitura; o servidor recusa escrita)

A chave name é um rótulo livre. Ela aparece no relatório e ajuda a ler o plano.

O passo form

O passo publica uma pasta de formulário, como o form export.

{"form": "forms/frm_pedido"}
{"form": "forms/frm_pedido", "documentId": 805585, "version": "keep"}
{"form": "forms/frm_novo", "new": true, "parentId": 15, "datasetName": "ds_pedido"}

• O alvo no servidor é resolvido como no comando: documentId > formName > mapeamento (.fluigcli/forms.json) > nome da pasta.
• A opção é formName porque a chave name já é o rótulo livre do passo.
• A criação precisa de "new": true, mais parentId e datasetName. Num plano não existe pergunta: sem a declaração, o passo falha dizendo o que declarar.
• O vínculo pasta↔documentId é gravado no .fluigcli/forms.json, no bucket do servidor, igual ao comando. O arquivo é versionável, então um release deixa essa alteração para você comitar.
• A auditoria do formulário usa o recorte de regras do form export: só RHINO* e FL* barram. As regras SG*, de tema visual, não impedem o release.

O passo workflow

O passo publica uma versão nova do processo com os scripts locais e a libera. É o mesmo que o workflow publish.

{"workflow": "Compras"}
{"workflow": "SolicitacaoAdiantamento", "processId": "Adiantamento ao Fornecedor"}
{"workflow": "Compras", "noRelease": true}

• O alvo é o prefixo dos arquivos locais (workflow/scripts/<prefixo>.*.js).
• processId aponta o processo no servidor quando o nome dele difere do prefixo.
• noRelease cria a versão em edição, sem liberar. A chave é negativa porque o valor padrão do plano é liberar, como no comando.

O workflow export (atualização cirúrgica na versão corrente) não existe como passo. Ele não versiona, é ferramenta de desenvolvimento e depende do componente auxiliar. Release é publish.

Os caminhos são relativos à raiz do projeto. Uma chave escrita errado (por exemplo datasets no lugar de dataset) é erro, não silêncio.

O plano nunca contém senha. A autenticação segue a precedência normal.

O que acontece na execução

1. A CLI lê e valida o plano inteiro. Um passo sem tipo, com dois tipos ou com chave desconhecida reprova o plano antes de qualquer conexão.
2. A CLI audita todos os scripts do plano com as regras do audit. Um achado de nível ERRO em qualquer script aborta o release, e nada é publicado. As pastas de formulário são auditadas numa passada separada, com o recorte de regras do form export. Use --no-audit para pular as duas.
3. A CLI autentica. Em servidor marcado como produção, vale a trava de confirmação — uma vez para o plano todo, não por passo.
4. Os passos rodam na ordem. A CLI para no primeiro erro.

Os passos não tentados saem como skipped no relatório. Assim você vê onde o release parou, e retoma com --from N depois de corrigir.

── [1] db sql/001_check.sql: 2 instrução(ões) de leitura executada(s)
── [2] dataset datasets/ds_jud_agenda.js: dataset ds_jud_agenda created
aviso: passo 3 (widget processos_judiciais): o código "processos_judiciais" já
existe no servidor como LAYOUT …
Plano interrompido no passo 3: 2 executado(s), 1 não tentado(s). Retome com --from 3.

--dry-run

O --dry-run valida o plano sem escrever nada:

• todos os arquivos e pastas existem;

• a auditoria dos scripts passa;

• cada dataset é classificado como criação ou atualização (a CLI consulta o servidor);

• o código do widget não colide com um layout (a guarda de widget export);

• o layout tem application.type=layout e o código não colide com um widget (a guarda de layout export);

• cada script .sql tem instruções reconhecíveis, com a contagem;

• cada evento local existe no processo. O --dry-run baixa o XML do processo e aplica os scripts em memória, sem importar nada. Um evento que não existe no processo aparece aqui, e não no meio da publicação:

  aviso: passo 1 (workflow Adiantamento ao Fornecedor): evento(s) eventoInventado
  não existem no processo "Adiantamento ao Fornecedor" — o publish não cria
  eventos; crie-os no Fluig Studio (nada foi alterado)

Rode o --dry-run antes de qualquer release em produção. Ele responde "este plano vai funcionar?" sem correr o risco.

Saída --json

{
  "ok": true,
  "command": "deploy",
  "server": "producao",
  "data": {
    "plan": "release.json",
    "dryRun": false,
    "steps": [
      {"index": 1, "name": "diagnóstico", "kind": "db", "target": "sql/001_check.sql",
       "status": "ok", "action": "2 instrução(ões) de leitura executada(s)"},
      {"index": 2, "kind": "dataset", "target": "datasets/ds_jud_agenda.js",
       "status": "failed", "error": "..."},
      {"index": 3, "kind": "widget", "target": "processos_judiciais", "status": "skipped"}
    ],
    "counts": {"ok": 1, "failed": 1, "skipped": 1}
  },
  "error": null
}

O status de cada passo é ok, failed, skipped (não tentado) ou validated (no --dry-run).

Exit codes

código	quando
0	todos os passos concluíram
1	a auditoria reprovou um script do plano (AUDIT_FAILED) — nada rodou
2	plano inválido, --from fora do intervalo, ou --dry-run com problema
4	o arquivo do plano não existe
6	o plano rodou em parte e parou (veja data.steps)

Quando o primeiro passo falha, o comando devolve o erro daquele passo, com o código dele. Não existe release parcial quando nada foi publicado.

Limitações

• Não há rollback. O Fluig não tem transação entre artefatos. O plano para no erro e diz onde parou — a volta é sua, com o Git e o dataset history.
• Os passos db são de leitura. Eles servem para diagnóstico e verificação dentro do release. A escrita continua recusada no servidor.