Referência da ferramenta

O nnconsole é a ferramenta do autor de módulo. Num repositório de módulo ela é chamada pelo wrapper ./nnconsolew, versionado ao lado do mvnw, que resolve o jar da versão do SDK do pom.xml e roda a JVM. Antes do primeiro módulo (quando ainda não existe um repositório com o wrapper), não há instalador: o CLI é o jar all publicado no repositório Maven da empresa — br.com.nnumbers.console:console-sdk-cli (0.8.0-SNAPSHOT), no grupo https://cicd.nnumbers.com.br/nexus/repository/maven-public/ (leitura sem credencial; o grupo também espelha o Maven Central):

MAVEN=https://cicd.nnumbers.com.br/nexus/repository/maven-public
SDK=0.8.0-SNAPSHOT                       # a versão do SDK desta linha
value=$(curl -sS "$MAVEN/br/com/nnumbers/console/console-sdk-cli/$SDK/maven-metadata.xml" \
  | awk '/<classifier>all<\/classifier>/{f=1} f && /<value>/{gsub(/.*<value>|<\/value>.*/,""); print; exit}')
curl -sS -o nnconsole-all.jar \
  "$MAVEN/br/com/nnumbers/console/console-sdk-cli/$SDK/console-sdk-cli-$value-all.jar"
java -jar nnconsole-all.jar version
# sdk 0.8.0-SNAPSHOT (nnconsole/0.8.0-SNAPSHOT), contrato console.nnumbers.io/v1alpha3

(O caminho -SNAPSHOT do arquivo 404; por isso o value do <snapshotVersions>.) Dentro de um repositório de módulo, o ./nnconsolew resolve o mesmo jar sozinho — o jar baixado só é necessário para o PRIMEIRO módulo; no repositório, um desenvolvedor precisa só de JDK 26 e do Maven Wrapper.

./nnconsolew version

sdk 0.8.0-SNAPSHOT (nnconsole/0.8.0-SNAPSHOT), contrato console.nnumbers.io/v1alpha3

Códigos de saída: 0 certo; 1 falha (a mensagem sai em stderr, prefixada por nnconsole:); 2 uso errado. As flags aceitam -nome valor, --nome valor, -nome=valor e --nome=valor, vêm antes dos argumentos posicionais, e -- encerra as flags. -h, -help e --help pedem o uso. Quase todo comando aceita --json para a saída de máquina.

Sem argumentos, o nnconsole lista os subcomandos:

uso: nnconsole descriptors validate | openapi check | nnp build|sign|verify|inspect|plan |
grants sign|verify|inspect|diff | docs check | template check | chart check |
netpolicy render|release|verify|probe | status check --targets … | api get|post|put|patch|delete |
modules show|plan|upload|deploy|rollback|disable|enable|retire|wait|probe-pause|probe-resume|fault-inject|fault-clear |
conformance validate|run | portability scan | secrets scan |
keys generate (--issuer … | --grant-key) (--seed-to-cmd | --out) | image inspect |
schema v1alpha3 <nome> | version | module create <id>

---

module create

Cria o módulo: a árvore completa (NNS em Java, descritores, chart, status, docs, help, embed, conformance e onboarding) no diretório de destino. O gerado não escreve fora do --dir.

./nnconsolew module create --dir nnumbers-console-notes \
  --package br.com.nnumbers.console.notes --name "Notes" notes

As flags vêm antes do id posicional — a ordem contrária é recusada (nnconsole: esperado exatamente um argumento: o id do módulo, exit 2).

flag	o que é	padrão
<id> (posicional)	o id do módulo: 3–40, ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, fora dos reservados e dos ids com dono	obrigatório
--dir	destino (criado ou vazio; um destino existente e não vazio é recusado)	./<id>
--package	pacote Java raiz (2–5 rótulos, terminando no id com _; palavra reservada é recusada)	br.com.nnumbers.console.<id com _>
--name	o nome de exibição	o id

O resumo vai para o stderr (módulo <id>@0.1.0 criado em <dir> (… arquivos)); o stdout é uma linha, o caminho do diretório criado. A árvore gerada já declara a audience nas rotas, no help, nas docs, no status e nas trilhas.

---

descriptors validate

Confere os descritores contra os schemas: é o primeiro gate de qualquer mudança.

./nnconsolew descriptors validate --dir nnp

ok: sample@0.1.0 (module)

flag	o que é	padrão
--dir	o diretório nnp/ ou a raiz do módulo	nnp
--targets, --target	conferem também o contrato de rede contra o target	—
--authorized	dependências a SUPOR autorizadas na conferência local (quem decide é o Module Manager no deploy)	—
--json	problemas em JSON	—

openapi check

Confere as rotas do api.yaml e o nns/api/openapi.yaml nos dois sentidos.

./nnconsolew openapi check --dir nnp

openapi: ok (2 rota(s))

Flags: --dir (padrão nnp), --json.

nnp build

Monta o .nnp: release.json, SBOM, checksums e o pacote.

./nnconsolew nnp build --root . --out dist --java-image <registry>/<repo>@sha256:<digest>

flag	o que é	padrão
--root	raiz do módulo (com nnp/release.yaml)	.
--out	diretório de saída	dist
--java-image	a imagem JVM do NNS, PUBLICADA, por digest: o nnconsole a lê do registry e o SBOM recebe o registro de runtime, o SDK do carimbo e os jars com SHA-256	—
--probe-java-image	a imagem JVM do Status Probe, publicada, por digest	—
--sbom	um SBOM CycloneDX pronto, se você já tem	gerado
--npm-lock	package-lock.json do NNC; repetível, um por surface	—
--nnc-packages	inventário dos pacotes npm EMBUTIDOS no bundle de uma surface; repetível, um por build	—
--build-id, --repository	UUID do build e URL do repositório	derivados

nnp sign

Assina o pacote com a seed Ed25519 (a seed fica FORA do repositório e nunca é impressa).

./nnconsolew nnp sign --key-file <seed> --key-id <kid> --out dist/<módulo>-<versão>.signed.nnp dist/<módulo>-<versão>.nnp

Flags: --key-file, --key-id (padrão: o da regra nova), --trusted-keys (JWKS para autoverificar), --out (padrão: sobrescreve a entrada).

nnp verify

Abre o pacote com o mesmo validador do Module Manager.

./nnconsolew nnp verify --signature-policy required --trusted-keys <jwks> dist/<módulo>-<versão>.nnp

Flags: --signature-policy (off|optional|required, padrão required), --trusted-keys, --sdk-version (padrão: a do validador), --json. Sem JSON, a última linha é ok: <release> <digest> (assinatura: <estado>).

nnp inspect

Lista o conteúdo do pacote.

./nnconsolew nnp inspect dist/<módulo>-<versão>.nnp

Flags: --json.

nnp plan

O plano de deploy em modo leitura: cada recurso e cada blocker, sem tocar na plataforma.

./nnconsolew nnp plan dist/<módulo>-<versão>.nnp --targets <targets> --target <id> --all-capabilities --simulate-greenfield

flag	o que é
--targets, --target	o arquivo de targets e o id do target
--signature-policy, --trusted-keys	a política de assinatura do pacote
--grants, --grant-keys	a política de grants assinada e o JWKS dela
--active-module <id>=<callers>	um módulo ACTIVE no registro, com os chamadores internos dele; repetível
--capabilities, --all-capabilities	as capabilities de plataforma disponíveis, ou todas
--simulate-greenfield	simula executor greenfield: unknown → will_create
--json	em JSON

grants sign|verify|inspect|diff

A política de grants de dependência privilegiada.

./nnconsolew grants sign --key-file <seed> --out <política-assinada> <política.json>
./nnconsolew grants verify --trusted-keys <jwks> --current <pacote-vigente> <pacote>
./nnconsolew grants inspect --trusted-keys <jwks> <pacote>
./nnconsolew grants diff --trusted-keys <jwks> <anterior|-> <novo>

Flags: sign — --key-file, --kid, --out; verify/inspect — --trusted-keys, --json (verify também aceita --current); diff — --trusted-keys.

docs check

Roda o perfil docs-mdx/v1 sobre o docs/ do módulo, sem empacotar.

./nnconsolew docs check --dir . --required --reserved-prefixes <lista>

flag	o que é	padrão
--dir	a raiz do módulo ou o nnp/	.
--required	política de produção: texto de template recusa	aviso
--reserved-prefixes	prefixos reservados do motor, separados por vírgula	vazio fora do Module Manager
--json	problemas em JSON	—

template check

Procura texto de template (nn-template-placeholder ou TROQUE) nos descritores, no help, no status e no NNC.

./nnconsolew template check --dir . --required

template: ok (0 aviso(s))

Flags: --dir (padrão .), --required, --json.

chart check

Renderiza o chart client-only e confere o manifesto contra a allowlist, com as regras do runtime JVM.

./nnconsolew chart check --values nns/helm/testdata/injected-values.yaml --namespace nns-sample-0-1-0 \
  --runtime jvm --runtime-user 1002 nns/helm/chart

ok: render client-only (v1.36.1) conferido; manifesto sha256:3f23aaca608289b30567f304c7a12c6cbe2a6e162bda0892490b54a98531db6a

flag	o que é	padrão
--values	os valores injetados (o bloco nnumbers)	obrigatório
--namespace	o namespace de destino (.Release.Namespace)	obrigatório
--kube-version	a versão do Kubernetes do target	v1.36.1
--runtime	jvm aplica chart_runtime_command, chart_runtime_env e chart_runtime_mount	vazio
--runtime-user	com --runtime jvm: o UID numérico da imagem; o runAsUser do chart tem de ser igual	—
--out	grava o manifesto conferido	—
--json	problemas em JSON	—

netpolicy render|release|verify|probe|surface-probe

A camada de rede: o que o Module Manager vai gerar e o que a sonda vai provar.

./nnconsolew netpolicy render  --targets <targets> --target <id> [--json]
./nnconsolew netpolicy release --targets <targets> --target <id> [--dir nnp] [--json]
./nnconsolew netpolicy verify  --targets <targets> --target <id> --tiers <json> --policies <json>
./nnconsolew netpolicy probe   --targets <targets> --target <id> --registry <f> --kubelet-host <ip>

render aceita --validation-object (só o objeto de teste do runbook de troca da política viva). verify e probe recebem o resultado de kubectl get (--tiers, --policies, --daemonset, --guard-pods, --nodes, --module-pods) e --apiserver-url repetível. probe também aceita --plan-only, --conformance-digest, --existing-module, --existing-catalog e --dir.

status check

Confere o contrato do Status Probe contra o target.

./nnconsolew status check --targets <targets> --registry <registry> --image <ref@sha256:…>

Flags: --targets, --dir (padrão .), --registry, --image (padrão: a do release.yaml), --env (production|development, padrão production), --json.

api get|post|put|patch|delete

Chama a Public API com o token do CLI.

./nnconsolew api get /v1/platform/health
./nnconsolew api post /v1/sample/items --json '{"name":"primeiro"}'

flag	o que é	padrão
--json, --file	o corpo literal, ou lido de um arquivo	—
--content-type	o Content-Type do corpo	application/json
--idempotency-key	a chave da mutação	gerada nas mutações
--header 'Nome: valor'	cabeçalho extra; repetível (Authorization e Cookie são recusados)	—
--raw	o corpo como veio, sem indentar	—
--api, --token-cmd	a URL da Public API (padrão: NN_API_URL) e o comando que imprime o bearer	device flow

modules …

O ciclo de vida no Module Manager, sempre pela ferramenta — nunca kubectl ou helm à mão.

./nnconsolew modules show [<id> [<rid>]]
./nnconsolew modules plan <id> <release>
./nnconsolew modules upload <pacote.nnp>
./nnconsolew modules deploy <id> <release>
./nnconsolew modules rollback <id> --to <release>
./nnconsolew modules disable <id>        # e enable
./nnconsolew modules retire <id> <release>
./nnconsolew modules wait <id> <release>
./nnconsolew modules probe-pause <id>    # e probe-resume
./nnconsolew modules fault-inject <id>   # e fault-clear
./nnconsolew modules tenants <id>        # e tenant-enable | tenant-disable <id> <gid>

flag	o que é	padrão
--api, --token-cmd	a Public API e o comando do bearer	NN_API_URL, device flow
--json	saída de máquina	—
--no-wait, --timeout	não acompanhar a Action; prazo do acompanhamento	acompanha; 30m
--idempotency-key	repetir a mesma chave torna o pedido seguro	gerada
--to	o alvo do rollback	obrigatório no rollback
--allow-audit-pending	aceita o registro de audit PENDING no deploy (nunca em kind: platform)	—
--ttl	segundos da pausa e da falha sintética (≤ 900)	300
--component, --result	componente e resultado da falha sintética (FAIL ou DEGRADED)	DEGRADED

conformance validate e conformance run

validate confere o tests/conformance.yaml contra a release, sem rede.

./nnconsolew conformance validate --dir . --expect tests/conformance.yaml

conformance: ok (sample, tests/conformance.yaml)

run prova a release ao vivo, com ids estáveis e estado retomável.

./nnconsolew conformance run --module sample --release sample@0.1.0 --out report.json \
  --api https://<host> --token-cmd '…' --phase package --phase nns

flag	o que é
--module, --release	o módulo e a release em prova (a ACTIVE)
--out	estado e relatório (JSON, sem token; retomável)
--phase	package|nns|api|audit|network|status|docs|audience|rollback; repetível
--package	o .nnp local da release (digest, NNC e OpenAPI comparados)
--docs-base, --status-base	a origem do portal e da página pública do Status
--allow-mutations, --rollback-to	libera as provas que mutam; o alvo do rollback
--api, --token-cmd	a Public API e o bearer (o valor nunca vai a log, arquivo ou argumento de outro processo)
--tenant-token-cmd, --platform-token-cmd	um principal de cada audience, para a fase audience
--evidence	o diretório das evidências de browser dos checks assistidos
--expect, --dir	as expectativas e a raiz do módulo

portability scan

Recusa host, IP, namespace, cluster ou localhost fixos.

./nnconsolew portability scan --dir .

portability: ok (sem .nnportability.yaml (só regras genéricas))

Flags: --dir (padrão .), --json.

secrets scan

Procura segredo no que está versionado.

./nnconsolew secrets scan --dir .

secrets: ok

Flags: --dir (padrão .), --json. Rode-o sozinho, conferindo o código de saída.

keys generate

Gera uma seed Ed25519 nova e imprime só o kid e a JWK pública.

./nnconsolew keys generate --issuer nnumbers-public-api --seed-to-cmd '<comando que guarda a seed>'
./nnconsolew keys generate --grant-key --seed-to-cmd '<comando>'

flag	o que é
--issuer	o emissor (nn_iss da JWK)
--grant-key	chave de assinatura da política de grants (nunca assina NNP)
--seed-to-cmd	comando que recebe a seed pelo stdin; repetível (produção)
--out	arquivo da seed 0600, fora do repositório, sem sobrescrever (desenvolvimento)
--nnp-kinds, --nnp-modules	chave de assinatura de NNP: module, platform ou ambos; ids de módulo separados por vírgula ou *

schema v1alpha3 <nome>

Imprime um dos schemas do contrato.

./nnconsolew schema v1alpha3 release
./nnconsolew schema v1alpha3 --bundle chart-values

A lista de nomes sai do próprio comando quando você o chama sem o nome.

image inspect

Lê uma imagem publicada por digest e diz o que ela é.

./nnconsolew image inspect --role nns <registry>/<repositório>@sha256:<digest>

Flags: --role (nns ou status-probe). A imagem em si é construída pelo Maven, não pela ferramenta:

./mvnw spring-boot:build-image -Dnn.image.name=<registry>/<repositório>

version

./nnconsolew version
# sdk 0.8.0-SNAPSHOT (nnconsole/0.8.0-SNAPSHOT), contrato console.nnumbers.io/v1alpha3