FEATURE ROLLOUT · DOCUMENTAÇÃO

Um contrato operacional para local e remoto

Docker CLI controla o processo local, fr controla a identidade pessoal e HTTP controla os recursos suportados. O host muda; o formato dos contratos permanece o mesmo.

Separe as três interfaces

Não trate docker, fr e curl como comandos equivalentes. Cada um atua em uma camada diferente e possui uma credencial própria.

dockerInicia, para, atualiza, inspeciona, faz backup e restaura a instância local

frAutentica por dispositivo e administra todos os recursos da Management API

HTTPExpõe Management API, ingestão CI, catálogo, cobertura, gates e diagnóstico

DashboardInterface humana sobre os mesmos recursos; suas rotas internas não são contrato de integração

Escopo atual da CLI

A versão 0.2 opera projetos, portfólios, features, cenários, evidências, riscos e documentos pela Management API. Tarefas continuam reconciliadas pelo catálogo v2 para preservar completude e vínculos.

Escolha o host explicitamente

Use FEATURE_ROLLOUT_URL em scripts e agentes para evitar que uma operação destinada ao Docker seja enviada à produção. O endpoint de saúde é o primeiro preflight de qualquer automação.

LOCALhttp://127.0.0.1:3000 · sem login web · dados no volume Docker

REMOTOhttps://feature-rollout.dev · sessão web ou Bearer conforme a rota

HEALTH200 com status=ok, database=connected e o modo efetivo

shell

# escolha exatamente um destino
export FEATURE_ROLLOUT_URL=http://127.0.0.1:3000
# export FEATURE_ROLLOUT_URL=https://feature-rollout.dev

curl --fail-with-body   --header 'Accept: application/json'   "$FEATURE_ROLLOUT_URL/api/health"

Autentique a CLI em cada host

As credenciais são salvas separadamente por origem. fr login abre a página de aprovação do próprio host; fr whoami --json é a saída estável para agentes e scripts.

shell

# Docker local: aprovação no navegador local, sem conta externa
fr login --host http://127.0.0.1:3000
fr whoami --host http://127.0.0.1:3000 --json
fr logout --host http://127.0.0.1:3000

# Plataforma remota
fr login --host https://feature-rollout.dev
fr whoami --host https://feature-rollout.dev --json

# escolha um host padrão para a sessão do terminal
export FEATURE_ROLLOUT_URL=https://feature-rollout.dev
fr whoami

Separe gestão e CI

O token fr_pat_* autentica identidade e Management API. Chaves fr_ci_* e credenciais OIDC continuam exclusivas para ingestão, catálogo e gates automatizados.

Use a credencial exigida por cada família

Uma resposta 401 normalmente indica credencial ausente ou inválida; 403 indica identidade válida sem papel, escopo ou confiança suficiente.

GET /api/health e /api/versionSem credencial

/api/v1/cli/*Bearer fr_pat_* emitido pelo login por dispositivo

/api/v2/management/*Bearer fr_pat_* com management:read/write e papel suficiente no workspace

/api/v1/test-results e coberturaBearer fr_ci_* com test-runs:write

/api/v2/test-runsBearer fr_ci_* com test-runs:write

/api/v2/catalogBearer confiável com catalog:write; atualmente emitido pelo GitHub OIDC

/api/v2/gates/evaluateBearer confiável com rollout:write; atualmente emitido pelo GitHub OIDC

Fluxo obrigatório para agentes

Um agente deve resolver o host, validar saúde, descobrir IDs, ler o estado, mostrar o diff, gravar e reler. Essa sequência vale tanto para chamadas HTTP quanto para automação de navegador.

01 PREFLIGHTGET /api/health e confirme local ou remoto

02 IDENTIDADEfr whoami para pessoa; valide escopos do token de CI pela origem

03 LEITURAObtenha IDs e estado atual; nunca derive UUID a partir do nome

04 PLANOMostre recurso, campos e efeito de substituição antes da escrita

05 ESCRITAUse timeout, --fail-with-body e Idempotency-Key/X-Run-ID quando disponível

06 VERIFICAÇÃOLeia novamente, confira IDs/contagens e registre a resposta

text

Use http://127.0.0.1:3000 como o Feature Rollout local.
Antes de qualquer mutação, consulte /api/health e leia o recurso atual.
Use somente o dashboard ou endpoints HTTP documentados; não altere o PostgreSQL diretamente.
Mostre o plano ou diff antes de gravar.
Não exclua projetos, documentos, containers ou volumes sem confirmação humana explícita.
Depois de cada gravação, leia o recurso novamente e informe os IDs alterados.

Use somente contratos públicos

A Management API em /api/v2/management/* é o contrato público e versionado para projetos, portfólios, features, cenários, evidências, riscos e documentações. Rotas internas do dashboard continuam protegidas por sessão e podem evoluir sem compatibilidade para automações; não copie cookies do navegador.

Não exponha o modo local

Como as rotas de gestão não exigem login no Docker, mantenha 127.0.0.1. Publicar a porta em 0.0.0.0 entrega permissão owner a qualquer cliente da rede.