@zenifra/cli 0.4.0 → 0.6.0

package/README.md

@@ -54,9 +54,16 @@ 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 plans --type job
 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
@@ -64,6 +71,7 @@ zenifra create project --name <name> --plan analytics-starter --payment-mode hou
 zenifra create project --name <name> --plan db-free --payment-mode hourly --config @examples/valkey-key-value-project.json
 zenifra create project --name <name> --plan cache-free --payment-mode hourly --config @examples/valkey-cache-project.json
 zenifra create project --name <name> --plan queue-free --payment-mode hourly --config @examples/valkey-queue-project.json
+zenifra create project --name nightly-report --plan job-basic --payment-mode per_minute --config @examples/job-project.json
 zenifra projects --type http --page 1 --limit 15
 zenifra projects --type valkey --page 1 --limit 15
 zenifra project info --project <project-id>
@@ -76,12 +84,18 @@ zenifra valkey credentials rotate --project <project-id> --wait
 zenifra valkey credentials status --project <project-id> --operation <operation-id>
 zenifra project url --project <project-id>
 zenifra project logs --project <project-id> --instance <instance-id>
+zenifra project runs --project <project-id> --page 1 --limit 20
+zenifra project runs cancel --project <project-id> --run <run-id>
+zenifra project runs logs --project <project-id> --run <run-id>
 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>
@@ -138,9 +152,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>
@@ -153,10 +167,37 @@ 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
@@ -239,7 +280,7 @@ zenifra plans --type database
 zenifra plans --type storage --json
 ```
 
-`zenifra plans` funciona sem autenticacao e mostra os catalogos publicos de HTTP, banco, armazenamento e Valkey. Use `--type valkey` para consultar Key Value, Cache e Queue.
+`zenifra plans` funciona sem autenticacao e mostra os catalogos publicos de HTTP, banco, armazenamento, Jobs agendados e Valkey. Use `--type job` para consultar Jobs agendados ou `--type valkey` para consultar Key Value, Cache e Queue.
 
 Para planos HTTP, a saida legivel tambem mostra as capacidades disponiveis, como logs, metricas, verificacao de saude, auto-scaling, subdominio personalizado e acesso de rede. Use `--json` quando precisar consumir o catalogo sem formatacao.
 
@@ -309,6 +350,7 @@ Use os arquivos em `examples/` como base para `zenifra create project`:
 - `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
@@ -316,6 +358,7 @@ Use os arquivos em `examples/` como base para `zenifra create project`:
 - `examples/valkey-key-value-project.json`: projeto Valkey Key Value com armazenamento persistente
 - `examples/valkey-cache-project.json`: projeto Valkey Cache sem armazenamento persistente
 - `examples/valkey-queue-project.json`: projeto Valkey Queue com armazenamento persistente
+- `examples/job-project.json`: Job agendado com cron UTC, imagem e armazenamento efêmero
 
 Se voce rodar apenas `zenifra create project`, a CLI abre um wizard interativo estilo `npm init` e pergunta todos os campos guiados. Cada pergunta mostra:
 
@@ -329,17 +372,18 @@ O wizard atual cobre:
 - projetos `postgresql`
 - projetos `mariadb`
 - projetos `valkey` nos perfis `key_value`, `cache` e `queue`
+- Jobs agendados com uma imagem OCI pronta
 
 Projetos `clickhouse` usam atualmente o fluxo nao interativo com `--config`, como em `examples/clickhouse-project.json`.
 
-`zenifra create project` nao assume valores default para `--plan` e `--payment-mode`.
+`zenifra create project` nao assume valores default para `--plan` e `--payment-mode`, exceto para Jobs, que usam `per_minute` automaticamente.
 Configs HTTP nao interativas tambem devem informar `config.exposure`; use `public` para criar rota/dominio publico ou `private` para manter a aplicacao sem exposicao na internet.
 Antes de escolher um plano com o usuario, compare os catalogos com `zenifra plans` para evitar suposicoes sobre custo.
 
 Valores aceitos:
 
-- `payment_mode`: `hourly`, `monthly`, `yearly`
-- `type_project` no `config`: `http`, `postgresql`, `mariadb`, `valkey`, `clickhouse`
+- `payment_mode`: `hourly`, `monthly`, `yearly`, `per_minute` (somente Jobs)
+- `type_project` no `config`: `http`, `postgresql`, `mariadb`, `valkey`, `clickhouse`, `job`
 - `exposure` no `config` HTTP: `public`, `private`
 - `plan`: consulte `zenifra plans` para os planos atuais; ClickHouse usa `analytics-*`; Valkey usa `db-*` para Key Value, `cache-*` para Cache e `queue-*` para Queue
 - `config.profile` em projetos Valkey: `key_value`, `cache` ou `queue`
@@ -348,7 +392,9 @@ Valores aceitos:
 - `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
+- `config.job` (somente Jobs): cron com cinco campos em UTC; o wizard usa a imagem OCI pronta e nao pergunta comando, argumentos, URL, exposicao, porta ou instancias
 
 Observacoes do wizard:
 
@@ -359,7 +405,8 @@ Observacoes do wizard:
 - 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
 - em projetos Valkey, a capacidade é definida pelo plano e a CLI não pergunta instâncias, imagem, variáveis de ambiente ou exposição HTTP
-- a conexão mascarada pode ser consultada a qualquer momento; uma rotação concluída pode salvar a conexão utilizável em arquivo privado com `--connection-file <path>`
+- em Jobs, a imagem OCI pronta é obrigatória, o cron usa cinco campos em UTC, a cobrança é por minuto inteiro e a CLI não pergunta origem GitHub, tipo de pagamento, comando, argumentos, exposição HTTP, porta ou instâncias
+- a conexão mascarada pode ser consultada a qualquer momento; a credencial completa aparece apenas na criação ou em uma rotação concluída, podendo ser salva em arquivo privado com `--connection-file <path>`
 - `valkey credentials rotate` retorna uma operação assíncrona; use `--wait` ou `valkey credentials status` para acompanhar
 
 Exemplo de entrega segura para automação local:
@@ -370,6 +417,20 @@ zenifra valkey credentials rotate --project <project-id> --wait --connection-fil
 
 O arquivo é criado com permissão privada; a conexão não aparece na saída do comando quando essa opção é usada.
 
+## Execuções de Jobs agendados
+
+Consulte o histórico de execuções e os logs de uma execução específica:
+
+```bash
+zenifra project runs --project <project-id>
+zenifra project runs cancel --project <project-id> --run <run-id>
+zenifra project runs logs --project <project-id> --run <run-id>
+```
+
+`project runs cancel` cancela somente a execução selecionada. O cron do projeto continua agendando novas execuções; use `zenifra project stop --project <project-id>` para pausar o projeto e interromper execuções futuras.
+
+O cancelamento aguarda até 30 segundos pela finalização segura e pode forçar o encerramento depois desse período. Se uma execução antiga não puder ser cancelada com segurança, o comando informa o problema e você deve aguardar que ela termine ou alcance o limite de tempo.
+
 ## Regressao manual de auto-scaling em staging
 
 O teste de staging cria projetos, gera trafego, consulta consumo e remove somente os projetos criados pela propria execucao. Ele exige uma API de teste explicita, rejeita a API de producao e exige habilitacao explicita das mutacoes. O exemplo abaixo usa uma API local de teste.