@zenifra/cli 0.3.4 → 0.5.0

package/README.md

@@ -54,9 +54,15 @@ zenifra plans
 zenifra plans --type http
 zenifra plans --type valkey
 zenifra plans --type storage --json
+zenifra git providers
+zenifra git runtimes
+zenifra git connections
+zenifra git repositories resolve --connection <connection-id> --path equipe/aplicacao
+zenifra git branches --connection <connection-id> --repository <repository-id>
 zenifra create project
 zenifra create project --name <name> --plan free --payment-mode hourly --config @examples/http-project.json
 zenifra create project --name <name> --plan basic --payment-mode hourly --config @examples/http-github-project.json
+zenifra create project --name <name> --plan basic --payment-mode hourly --config @examples/http-git-project.json
 zenifra create project --name <name> --plan premium --payment-mode hourly --config @examples/http-autoscaling-project.json
 zenifra create project --name <name> --plan db-basic --payment-mode monthly --config @examples/postgresql-project.json
 zenifra create project --name <name> --plan db-basic --payment-mode monthly --config @examples/mariadb-project.json
@@ -80,6 +86,13 @@ zenifra project metrics --project <project-id> --instance <instance-id>
 zenifra project metrics capabilities --project <project-id>
 zenifra project network --project <project-id> --view summary
 zenifra project image set --project <project-id> --image ghcr.io/zenifra/app:tag
+zenifra project github --project <project-id>
+zenifra project github deploy-settings set --project <project-id> --mode branch
+zenifra project source --project <project-id>
+zenifra project source branches --project <project-id>
+zenifra project source deploy-settings set --project <project-id> --mode branch
+zenifra project github deploy-settings set --project <project-id> --mode tag --tag-pattern "v*"
+zenifra project github deploy-settings set --project <project-id> --mode release --tag-pattern "v*" --include-prereleases true
 zenifra project envs --project <project-id>
 zenifra project env add --project <project-id> --name NODE_ENV --value production
 zenifra project env update --project <project-id> --name NODE_ENV --value staging
@@ -134,9 +147,9 @@ zenifra project metrics capabilities --project <project-id> --json
 
 ---
 
-## Builds GitHub
+## Builds e deployments Git
 
-Use `zenifra builds` para listar o historico de builds e `zenifra builds logs` para ler os logs do pipeline GitHub de um build especifico.
+Use `zenifra builds` para listar o historico de builds e `zenifra builds logs` para ler os logs de um build de projeto com origem Git.
 
 ```bash
 zenifra builds --project <project-id>
@@ -149,12 +162,55 @@ zenifra deploy watch --project <project-id> --build <build-id>
 Fluxos:
 
 - `zenifra project logs`: logs da aplicacao em execucao
-- `zenifra builds logs`: logs do build GitHub
-- `zenifra deploy`: dispara o build/deploy GitHub e retorna o `build_id`
+- `zenifra builds logs`: logs do build Git
+- `zenifra deploy`: dispara o build/deploy Git e retorna o `build_id`
 - `zenifra deploy watch`: usa esse `build_id` para acompanhar o build em tempo real e imprimir os logs incrementais ate o fim
 
+Para criar um projeto HTTP com uma origem Git Forgejo, primeiro uma pessoa proprietaria da organizacao cria a conexao no Console. A CLI lista e usa conexoes existentes; ela nao solicita nem exibe credenciais do provedor.
+
+Use os catalogos para conferir provedores, capacidades e runtimes, depois resolva o caminho explicito do repositorio. O ID opaco retornado pertence a essa conexao e deve ser usado com ela ao listar branches:
+
+```bash
+zenifra git providers --json
+zenifra git runtimes
+zenifra git connections --json
+zenifra git repositories resolve --connection <connection-id> --path equipe/aplicacao --json
+zenifra git branches --connection <connection-id> --repository <repository-id>
+```
+
+Use os IDs confirmados em `config.source` e `config.build`, como no arquivo `examples/http-git-project.json`, para criar o projeto. Esse exemplo contem valores ilustrativos e nao credenciais:
+
+```bash
+zenifra create project --name api-web --plan basic --payment-mode hourly --config @examples/http-git-project.json
+zenifra project source --project <project-id> --json
+zenifra project source branches --project <project-id>
+zenifra project source deploy-settings set --project <project-id> --mode branch
+zenifra deploy --project <project-id> --branch main
+zenifra deploy watch --project <project-id> --build <build-id>
+```
+
+O deploy manual retorna um ID de build para acompanhar com `zenifra deploy watch`. Para ativar deploy por tag ou release, use `zenifra project source deploy-settings set --project <project-id> --mode tag --tag-pattern "v*"` ou o modo `release`; prereleases podem ser habilitadas somente no modo `release`. O comando preserva a origem e as configuracoes de build e confirma a alteracao com uma leitura posterior. A API nao oferece precondicao de revisao para essa atualizacao; evite alterar a origem ao mesmo tempo pelo Console ou por outro cliente. Projetos com configuracao GitHub legada continuam usando `zenifra project github` e `zenifra project github deploy-settings set`.
+
+Em APIs antigas que ainda nao anunciam as rotas Git neutras, a CLI usa as rotas anteriores somente quando consegue confirmar a origem GitHub legada do projeto. Essa verificacao pode exigir permissao de leitura do projeto. Se a API negar essa leitura, a CLI encerra o comando sem tentar a rota antiga; projetos Forgejo ou com outra origem generica nunca sao tratados como GitHub.
+
 Alguns builds antigos podem disponibilizar somente um resumo terminal. Nesse caso, a saida legivel avisa que eventos detalhados nao estavam disponiveis; `--json` preserva a resposta recebida da API.
 
+### Modos de deploy GitHub
+
+Consulte a configuracao publica atual e escolha exatamente um modo de deploy:
+
+```bash
+zenifra project github --project <project-id>
+zenifra project github deploy-settings set --project <project-id> --mode manual
+zenifra project github deploy-settings set --project <project-id> --mode branch
+zenifra project github deploy-settings set --project <project-id> --mode tag --tag-pattern "v*"
+zenifra project github deploy-settings set --project <project-id> --mode release --tag-pattern "v*" --include-prereleases false
+```
+
+Os modos aceitos sao `manual`, `branch`, `tag` e `release`. `tag` e `release` exigem `--tag-pattern`, que aceita curingas `*` e `?`. O padrao de prereleases e `false`; a opcao so esta disponivel no modo `release`. A CLI le a configuracao salva de volta antes de confirmar uma alteracao. O comando `zenifra deploy --project <project-id> --branch <branch>` continua disponivel para iniciar um deploy manual.
+
+Para criar um projeto HTTP com deploy por tag ou release, use `examples/http-github-tag-project.json` (padrao exato `v1.2.3`) ou `examples/http-github-release-project.json` (padrao `v*`).
+
 Antes de uma mutacao, confirme o perfil, a API e a organizacao ativa. Para criacoes, confirme tambem o catalogo, plano, pagamento, exposicao, dominio, origem do deploy, porta, instancias e ambientes. Depois, leia o projeto de volta e acompanhe o build/deployment ate um estado terminal.
 
 O dominio principal e um dominio personalizado sao campos diferentes. Nao repita o dominio principal em `config.custom_domains`; depois de adicionar um dominio personalizado, valide DNS/TLS e leia a URL final antes de considerar a operacao concluida.
@@ -287,6 +343,9 @@ Use os arquivos em `examples/` como base para `zenifra create project`:
 
 - `examples/http-project.json`: projeto HTTP com imagem OCI publica
 - `examples/http-github-project.json`: projeto HTTP com build via GitHub
+- `examples/http-github-tag-project.json`: projeto HTTP com deploy por tag e padrao exato
+- `examples/http-github-release-project.json`: projeto HTTP com deploy por release e padrao `v*`
+- `examples/http-git-project.json`: projeto HTTP com origem Git por conexao configurada no Console/API
 - `examples/http-autoscaling-project.json`: projeto HTTP pago criado com auto-scaling
 - `examples/postgresql-project.json`: projeto PostgreSQL
 - `examples/mariadb-project.json`: projeto MariaDB
@@ -324,12 +383,16 @@ Valores aceitos:
 - `config.version` em projetos Valkey: a versão retornada por `zenifra plans --type valkey`
 - `config.storage` em projetos Valkey: obrigatório e persistente para Key Value/Queue; omitido para Cache
 - `config.github.runtime` (quando houver GitHub em projeto HTTP): `nodejs` ou `python`
+- `config.github.auto_deploy`: use `true` para o modo `branch`; mantenha `false` ao habilitar `version_deploy`
+- `config.github.version_deploy`: use `enabled: true`, `event: "tag"` ou `"release"` e um `tag_pattern` explicito; `include_prereleases` e opcional e padrao `false`
+- `config.source` e `config.build` (quando houver origem Git por conexao): use os IDs retornados pela configuracao segura no Console/API; nao informe credenciais Git nesses campos
 - `config.autoscaling` (somente HTTP pago): `enabled: true`, `max_instances` maior ou igual a `config.instances` e alvos opcionais de CPU/memoria entre 1 e 100
 
 Observacoes do wizard:
 
 - conflitos entre documentacao e API sao validados pelo contrato real aceito pela API
 - o wizard oferece auto-scaling apenas quando o plano selecionado informa essa disponibilidade
+- no modo GitHub, o wizard permite escolher entre `manual`, `branch`, `tag` e `release`; modos por versao exigem um padrao de tags
 - na criacao com auto-scaling, `config.instances` e o minimo inicial e `config.autoscaling.max_instances` e o maximo
 - em projetos de banco, o wizard nao pergunta `username`, `password` nem `database name`
 - em projetos de banco, a CLI preenche apenas campos tecnicos minimos exigidos pela validacao atual da API