@zaip-ai/cli 2.2.0 → 2.6.0

package/templates/.agents/skills/zaip-skill-github-actions-setup/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: zaip-skill-github-actions-setup
+description: Configure GitHub Actions end to end for npm publishing, Cloudflare Pages frontend or Hostinger VPS backend, guiding credential setup and verifying access and deployments. Use for CI/CD onboarding or broken deployment credentials, not a routine GitHub push.
+---
+
+# Configurar GitHub Actions com o usuário
+
+Entregue workflows específicos do projeto, um guia preenchido com nomes exatos, testes executados e evidências. Acompanhe correções até funcionar ou até uma dependência concreta impedir o próximo passo; não encerre apenas entregando YAML.
+
+## Descoberta e autorização
+
+1. Leia configuração, remotes, workflows, manifests, lockfile e scripts de build/deploy existentes. Identifique repositório, pacote/app, diretório, provedor, ambiente, branch, runner e estratégia de release. Reutilize nomes já válidos.
+2. Pergunte somente o que falta: destinos desejados (npm, Pages, VPS, Supabase migration ou combinação), conta/projeto, ambiente e acesso administrativo. Faça poucas perguntas por vez. Não peça credenciais de provedores que não serão usados. Para migrations, explique antes que uma beta Supabase persistente pode gerar custo e obtenha confirmação explícita antes de criar branch hospedada, integração, GitHub App, secret ou workflow.
+3. Distinga configuração local, cadastro de credenciais, push, execução de verificação e deploy real. Reutilize autorização já dada. Prepare arquivos e comandos revisáveis antes de pedir autorização ainda ausente para publicar, alterar servidor ou promover produção.
+4. Nunca peça tokens, senhas, chaves privadas, OTP ou recovery codes no chat, screenshots ou registros. Peça cadastro diretamente no destino indicado e confirmação apenas de nome/escopo. Credencial local já existente segue [local-credentials](../zaip-skill-local-credentials/SKILL.md), sem busca global.
+5. Leia [contrato de secrets e testes](references/github.md) e somente as trilhas escolhidas: [npm](references/npm.md), [Cloudflare Pages](references/cloudflare-pages.md), [Hostinger VPS](references/hostinger-vps.md). Consulte as fontes oficiais ali vinculadas antes de configurar: telas, requisitos, permissões e versões podem mudar.
+
+## Implementação guiada
+
+6. Produza uma tabela preenchida: nome exato, secret ou variable, origem, escopo GitHub, job consumidor e teste. Use os nomes de referência em projetos novos; nomes existentes exigem mapeamento explícito no guia, scripts e YAML. A pessoa não deve adivinhar o que preencher.
+7. Explique cada cadastro na ordem das telas, valor esperado sem exibi-lo, onde salvar e como confirmar. GitHub Environment por ambiente é preferível quando disponível; repository secrets são alternativa explícita. IDs/configuração pública ficam em variables. Secrets de runtime ficam no servidor/secret manager; nada secreto entra em bundle frontend.
+8. Crie apenas os workflows selecionados no repositório do usuário e um guia operacional sem segredos. Separe verificação de publicação; modo verificar não pode subir pacote, criar deployment, reiniciar serviço ou mudar dados. Primeiro valide YAML, comandos, build e empacotamento locais.
+9. Integre ao stack: npm publica o tarball validado; Pages recebe o output real; VPS recebe artefato identificado por SHA e segue o runtime existente. Migrations usam o repositório central e `deploy.database.branch: beta`, com GitHub Integration como aplicador hospedado; o workflow nunca executa SQL direto em produção. Fixe actions por SHA verificado e ferramentas por versão compatível. Não entregue placeholders executáveis como configuração concluída.
+10. Use [deployment-pipeline](../zaip-skill-deployment-pipeline/SKILL.md) para entrega; [cloudflare-github-deploy](../zaip-skill-cloudflare-github-deploy/SKILL.md) para Pages; [github-deploy](../zaip-skill-github-deploy/SKILL.md) somente para publicação GitHub autorizada. Provisionamento VPS/DNS é outra operação: [hostinger-cloudflare-terraform](../zaip-skill-hostinger-cloudflare-terraform/SKILL.md) aplica-se apenas quando solicitado.
+
+## Verificação até o destino
+
+11. Confira nomes e escopos via UI ou `gh secret list` / `gh variable list`, sem tentar recuperar valores. Isso comprova cadastro, não funcionamento.
+12. Execute o job de verificação no GitHub com os mesmos secrets, environment e destino do deploy. Investigue logs sanitizados; corrija nome, escopo, permissão, expiração, trust ou conectividade e repita o teste que falhou.
+13. Faça deploy de teste somente no destino autorizado. npm requer versão nova real e canal explícito; Pages usa preview explícito; VPS usa staging/serviço escolhido. Ambiente indisponível não autoriza testar produção.
+14. Aguarde o run e verifique provedor e consumidor. Registre workflow/run URL, SHA, ambiente, artefato/versão, smoke e limites. Não confunda token ativo, SSH conectado, dry-run ou HTTP 200 genérico com publicação funcional.
+15. Termine com estados separados: configurado, autenticação/acesso verificados, deploy verificado, pendências e próximo passo exato. Se depender do usuário, indique a tela/campo pendente; retome dali sem refazer cadastros concluídos.
+
+## Portabilidade
+
+Esta skill e seus recursos podem acompanhar o instalador npm. Sua instalação não cria workflows ativos, secrets, contas, recursos nem solicita credenciais. Workflows são gerados sob demanda para o projeto selecionado. O workflow npm exclusivo do mantenedor ZAIP-AIOS permanece fora do pacote; esta skill não recupera a antiga publicação npm local.

package/templates/.agents/skills/zaip-skill-github-actions-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Configurar GitHub Actions"
+  short_description: "Guie credenciais e testes de npm, Pages e VPS"
+  default_prompt: "Use $zaip-skill-github-actions-setup para configurar meu deploy pelo GitHub Actions, orientar credenciais e verificar o resultado ponta a ponta."

package/templates/.agents/skills/zaip-skill-github-actions-setup/references/cloudflare-pages.md

@@ -0,0 +1,33 @@
+# Frontend no Cloudflare Pages
+
+## Conta, projeto e token
+
+1. Identifique app, lockfile, diretório, build e output real. Confirme Pages; Workers segue a skill especializada. Verifique dono atual do deploy: Git integration ou Actions; não ative ambos para o mesmo evento.
+2. Cloudflare Dashboard → Workers & Pages → projeto: confirme nome, conta e production branch. Projeto novo: Create application → Pages → Direct Upload, conforme UI atual; criação externa depende de autorização.
+3. Account ID da conta/painel vai em variable **CLOUDFLARE_ACCOUNT_ID**; nome do projeto em **CLOUDFLARE_PAGES_PROJECT**. Esses valores não são tokens.
+4. Perfil → API Tokens → Create Token → Custom token: Account → Cloudflare Pages → Edit; limite Account Resources à conta alvo. Defina validade/rotação. Não conceda DNS Edit, Global API Key ou todas as contas por conveniência.
+5. Token de usuário vai diretamente para GitHub secret **CLOUDFLARE_API_TOKEN**, environment **pages-preview**. Token existente de conta pode usar endpoint diferente; preserve o tipo e adapte o probe, sem substituir automaticamente.
+6. **CLOUDFLARE_PAGES_BRANCH** é preview explícito, diferente da production branch. Verifique pela API/configuração antes do upload. Produção tem job/environment e autorização próprios.
+
+## Testar dentro do Actions
+
+O helper [verify-cloudflare.mjs](../scripts/verify-cloudflare.mjs) faz somente GET para token de usuário: verifica estado ativo e leitura do projeto exato. Saída contém etapas/resultados sanitizados. Conta/projeto inválidos falham antes da rede. Use Node >=22.14 e este passo dentro de job com o mesmo environment do deploy:
+
+```yaml
+- name: Verify Cloudflare access
+  env:
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+    CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+    CLOUDFLARE_PAGES_PROJECT: ${{ vars.CLOUDFLARE_PAGES_PROJECT }}
+  run: node .agents/skills/zaip-skill-github-actions-setup/scripts/verify-cloudflare.mjs
+```
+
+Se a skill instalada não for versionada, copie o helper revisado para script project-owned e ajuste o caminho no workflow. GET aprovado comprova leitura, **não** upload. Não imprima token, curl verbose ou resposta integral que possa conter configuração sensível. O helper recusa redirects e oculta corpos/erros remotos. 401/403 pede correção de validade/conta/permissão; 404 pede conferir projeto/conta, não ampliar token.
+
+## Entrega e smoke
+
+Use Wrangler fixado e instalado pelo lockfile, pages deploy do output verificado, --project-name e --branch explícitos. Passe env validado e argumentos citados. Build ocorre antes de disponibilizar token. VITE_*/NEXT_PUBLIC_* são públicos no bundle: nenhum segredo ali. Secrets de Functions/runtime ficam no store Cloudflare apropriado, separados do token de upload.
+
+Com autorização, envie preview e capture deployment ID/URL; confira conta, projeto, branch, SHA e estado na API. GET na URL exata deve validar conteúdo identificável da aplicação, rota principal, assets e navegação/fallback aplicáveis. HTTP 200 de página padrão/login não prova frontend correto. Corrija build/output, token somente leitura, branch indevida ou SPA e reteste. Registre URL/SHA sem configuração sensível.
+
+Fontes: [CI Direct Upload](https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/), [Consultar projeto](https://developers.cloudflare.com/api/resources/pages/subresources/projects/methods/get/), [Token de usuário](https://developers.cloudflare.com/api/resources/user/subresources/tokens/), [Token de conta](https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/).

package/templates/.agents/skills/zaip-skill-github-actions-setup/references/github.md

@@ -0,0 +1,63 @@
+# GitHub: cadastro, contrato e execução
+
+## Preencha primeiro o contrato do projeto
+
+Informe OWNER/REPO verificado, branch autorizada, environment, filename, diretório da aplicação, comando de build, alvo de teste e alvo de produção. Campos deste guia devem ser resolvidos, nunca usados como defaults de produção.
+
+Padrão para projetos novos; preserve nomes existentes com mapeamento explícito:
+
+| Destino / environment sugerido | Nome exato | Tipo | Origem / consumidor |
+| --- | --- | --- | --- |
+| npm / npm | Nenhum token no modo OIDC | Trust no npm | Identidade GitHub do job publicador |
+| npm / npm | NPM_TOKEN | Secret, só fallback | Token granular, mapeado a NODE_AUTH_TOKEN só no passo npm |
+| Pages / pages-preview | CLOUDFLARE_API_TOKEN | Secret | Token de usuário, job Pages |
+| Pages / pages-preview | CLOUDFLARE_ACCOUNT_ID | Variable | Conta Cloudflare, job/probe Pages |
+| Pages / pages-preview | CLOUDFLARE_PAGES_PROJECT | Variable | Nome exato do projeto |
+| Pages / pages-preview | CLOUDFLARE_PAGES_BRANCH | Variable | Preview diferente da production branch |
+| VPS / vps-staging | VPS_SSH_PRIVATE_KEY | Secret | Chave exclusiva de deploy, job SSH |
+| VPS / vps-staging | VPS_KNOWN_HOSTS | Variable | Chave pública do host verificada fora da conexão |
+| VPS / vps-staging | VPS_HOST | Variable | IP/hostname real |
+| VPS / vps-staging | VPS_PORT | Variable | Porta SSH real |
+| VPS / vps-staging | VPS_USER | Variable | Usuário de deploy |
+| VPS / vps-staging | VPS_DEPLOY_PATH | Variable | Diretório de releases |
+| VPS / vps-staging | VPS_SERVICE | Variable | Serviço real |
+| VPS / vps-staging | VPS_HEALTH_URL | Variable | Endpoint HTTPS da API |
+
+Host pode ser secret por privacidade; ajuste o contexto em todo YAML. Nenhum GitHub PAT é necessário por padrão: GITHUB_TOKEN é fornecido pelo Actions. Não solicite senha npm/Cloudflare/Hostinger nem token Hostinger para deploy SSH.
+
+## Cadastro pela interface
+
+1. Abra o repositório correto → Settings. Confirme permissão de administração do environment; se faltar, peça o cadastro ao administrador.
+2. Em Environments, crie/selecione o nome exato do guia. Configure branches/tags permitidos e proteção de produção disponível no plano. O job declara exatamente esse environment.
+3. Environment secrets → Add secret: copie o nome do guia e cole o valor diretamente do provedor no GitHub. Preserve quebras de linha da chave privada. Salve; não cole na conversa.
+4. Environment variables → Add variable: cadastre cada configuração não secreta pelo nome exato.
+5. Se environments não estiverem disponíveis, escolha repository scope conscientemente: Settings → Secrets and variables → Actions → Secrets → New repository secret; aba Variables → New repository variable. Não suponha proteção de ambiente inexistente.
+6. Confirme somente os nomes. Secrets homônimos em environment/repository/organization podem se sobrepor; investigue o escopo que o job recebe.
+
+Alternativa no terminal **do usuário**, com entrada interativa protegida:
+
+```sh
+gh secret set CLOUDFLARE_API_TOKEN --repo OWNER/REPO --env pages-preview
+gh secret list --repo OWNER/REPO --env pages-preview
+gh variable list --repo OWNER/REPO --env pages-preview
+```
+
+Substitua OWNER/REPO e ambiente pelos valores resolvidos. Chave multilinha: prefira UI. Não use --body com valor secreto, echo, leitura de clipboard pelo agente, arquivo versionado ou logs de debug. Arquivo temporário, se necessário, é privado, fora do repo e removido após envio seguro. Não solicite códigos de 2FA; reaproveite sessão autenticada.
+
+## Contrato dos workflows produzidos
+
+- Configure workflow_dispatch para verificação sem mutação; job/arquivo separado ou input tipado com verify por padrão. Publicação recebe ambiente/canal/ref delimitados e depende das validações.
+- Restrinja repositório e refs, environment, permissions, timeout e concorrência por destino; produção exige promoção autorizada. Nunca exponha secrets a código de fork/PR não confiável, especialmente pull_request_target com checkout do PR.
+- Passe dados de evento/input/variables via env, valide allowlists e cite argumentos. Não interpole esses valores diretamente no shell. SSH usa shell remoto: valide parâmetros antes de compor o comando remoto.
+- Credenciais só no passo necessário. Instalação/build e smoke não herdam token de escrita. Não use set -x, printenv, dumps de contexto, curl -v ou upload de .npmrc/.ssh/.env.
+- Instale pelo lockfile e vincule o artefato ao SHA. Fixe actions por SHA confirmado no repositório oficial; nunca invente SHA.
+- workflow_dispatch exige workflow presente na default branch. Se for produção, não faça merge implícito: prepare a mudança e obtenha autorização necessária. A ref selecionada respeita filtro do ambiente.
+- Eventos gerados com GITHUB_TOKEN podem não disparar outro workflow. Avalie o evento real; workflow_dispatch é opção explícita sem PAT amplo automático.
+
+## Acompanhar e corrigir
+
+Com autorização aplicável, execute `gh workflow run FILENAME --repo OWNER/REPO --ref BRANCH` com inputs definidos no workflow. Identifique o run por workflow, event, ref, horário e SHA; não escolha o último run concorrente. Use `gh run watch RUN_ID --repo OWNER/REPO --exit-status`.
+
+Secret ausente pede checagem de nome/escopo, environment, disponibilidade em fork/Dependabot/reusable workflow e proteções pendentes. Não regenere credencial válida antes disso. Segredo exposto em log exige revogação/rotação e tratamento no provedor; nunca copie o valor ao relatório.
+
+Fontes: [Secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets), [Environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments), [Triggers](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).

package/templates/.agents/skills/zaip-skill-github-actions-setup/references/hostinger-vps.md

@@ -0,0 +1,55 @@
+# Backend em Hostinger VPS existente
+
+## Descoberta e contrato
+
+Inspecione runtime (systemd, Docker Compose, outro), artefato, OS/arquitetura, proxy/TLS, health endpoint, diretório e rollback. Não imponha Docker, Terraform ou dois VPS a servidor existente. SSH não requer token da API Hostinger. Provisionamento, DNS e migrations precisam do escopo correspondente.
+
+Preencha cada campo: VPS_HOST, VPS_PORT, VPS_USER, VPS_DEPLOY_PATH, VPS_SERVICE, VPS_HEALTH_URL, VPS_KNOWN_HOSTS e secret VPS_SSH_PRIVATE_KEY; environment sugerido vps-staging. Não assuma porta 22, root, serviço nem produção.
+
+## Obter acesso e cadastrar
+
+1. hPanel → VPS → Manage → Overview: confirme IP e SSH; use porta efetiva. Web Console fornece primeiro acesso. Senha root fica com usuário, não no GitHub.
+2. Identifique/crie quando autorizado usuário de deploy com acesso só à pasta/comandos necessários. Evite sudo irrestrito; grupo docker equivale a privilégio elevado e precisa ser justificado.
+3. Na máquina confiável do usuário, fora do repo, gere chave dedicada: `ssh-keygen -t ed25519 -C github-actions-deploy`; escolha filename novo, sem sobrescrever chave existente. Comando solicita destino/passphrase. A receita abaixo usa chave de automação sem passphrase, restrita no servidor e protegida no GitHub. Se a política exigir passphrase, implemente/teste ssh-agent e secret adicional antes de continuar; não retire proteção de chave pessoal.
+4. Pelo console/conexão confiável, acrescente somente a chave **pública** .pub ao authorized_keys do usuário de deploy, preservando entradas. Confirme ownership do usuário, .ssh 700 e authorized_keys 600. Restrinja forwarding/comandos quando compatível com upload; teste sem bloquear administrador.
+5. Cole chave **privada completa**, com cabeçalho/rodapé/quebras de linha, diretamente no GitHub → vps-staging → secret VPS_SSH_PRIVATE_KEY. Não confunda .pub com privada; não salve em .env/repositório.
+6. Pelo Web Console confiável, obtenha chave pública do host e fingerprint (exemplo `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`). Monte VPS_KNOWN_HOSTS: `HOST ssh-ed25519 PUBLIC_KEY` na porta padrão ou `[HOST]:PORT ssh-ed25519 PUBLIC_KEY` em porta customizada, com host e chave verificados.
+7. ssh-keyscan sozinho não autentica o servidor. Se coletar por ele, compare fingerprint ao console antes de salvar. Divergência bloqueia conexão; nunca use StrictHostKeyChecking=no como correção.
+8. Cadastre demais variables conforme destinos existentes. Secrets da aplicação ficam em arquivo/store protegido no VPS; workflow recebe só credencial de deploy. Imagem privada pode exigir leitura do registry, separadamente e apenas se necessária.
+
+## Teste sem alterar aplicação
+
+Gere job Linux com timeout, mesmo environment do deploy e Bash. Mapear env não é interpolar valores no script. Complete o fragmento com permissions, refs e versões do contrato GitHub:
+
+```bash
+set -euo pipefail
+[[ "$VPS_HOST" =~ ^[A-Za-z0-9][A-Za-z0-9.-]*$ ]] || exit 2
+[[ "$VPS_PORT" =~ ^[0-9]{1,5}$ ]] || exit 2
+(( 10#$VPS_PORT >= 1 && 10#$VPS_PORT <= 65535 )) || exit 2
+[[ "$VPS_USER" =~ ^[a-z_][a-z0-9_-]*$ ]] || exit 2
+test -n "$VPS_SSH_PRIVATE_KEY"
+test -n "$VPS_KNOWN_HOSTS"
+umask 077
+ssh_tmp="$(mktemp -d)"
+trap 'rm -f -- "$ssh_tmp/key" "$ssh_tmp/known_hosts"; rmdir -- "$ssh_tmp"' EXIT
+printf '%s\n' "$VPS_SSH_PRIVATE_KEY" > "$ssh_tmp/key"
+printf '%s\n' "$VPS_KNOWN_HOSTS" > "$ssh_tmp/known_hosts"
+unset VPS_SSH_PRIVATE_KEY
+ssh -F /dev/null -i "$ssh_tmp/key" -p "$VPS_PORT" \
+  -o BatchMode=yes -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes \
+  -o ConnectTimeout=15 -o ConnectionAttempts=1 \
+  -o UserKnownHostsFile="$ssh_tmp/known_hosts" \
+  "$VPS_USER@$VPS_HOST" 'true'
+```
+
+Exemplo aceita hostname/IPv4; adapte/teste se precisar IPv6. Depois acrescente comandos read-only do runtime: identidade esperada, pasta, espaço e estado do serviço. Valide paths/service contra contrato restrito antes do shell remoto; aspas locais não bastam para SSH. Não faça restart, mkdir/upload, migrations ou docker pull no modo verify.
+
+Runner sem conectividade: cheque DNS/porta/firewall e política de rede; não libere SSH para toda Internet automaticamente. Use solução aprovada de rede privada/runner adequado. Permission denied pede usuário, par de chaves e permissões. Host key mismatch exige validação pelo console.
+
+## Deploy e retorno
+
+Prepare artefato identificado por SHA/checksum em CI. Implemente upload para release nova, integridade remota, ativação atômica compatível e restart/reload só do serviço permitido. Não use git pull irrestrito ou rsync --delete sobre dados/secrets. Backup/migrations seguem contrato de dados; rollback de código não desfaz banco.
+
+Teste no staging/serviço autorizado. Confirme readiness local e HTTPS em VPS_HEALTH_URL, identidade/versão implantada e resposta esperada da API. Não exponha logs sensíveis. Se falhar, capture diagnóstico sanitizado, restaure release anterior pelo procedimento preparado quando seguro/autorizado e confirme health. Registre SHA, artefato, serviço, run e resultado; SSH conectado não é backend implantado.
+
+Fonte: [SSH e Web Console Hostinger](https://www.hostinger.com/support/5723772-how-to-connect-to-your-vps-via-ssh-at-hostinger/). Consulte documentação do runtime/proxy observado antes de escrever ativação.

package/templates/.agents/skills/zaip-skill-github-actions-setup/references/npm.md

@@ -0,0 +1,30 @@
+# npm: trust, publicação e prova
+
+Resolva pacote, registry, visibility, diretório, versão SemVer, canal, branch e filename. Leia package.json, publishConfig, files e hooks. Não imponha a versão do framework a consumidores. No mantenedor ZAIP-AIOS reutilize seu workflow exclusivo, sem outro publicador.
+
+## Trusted Publishing, opção preferida
+
+1. Usuário entra no npm como mantenedor do pacote → página do pacote → Settings → Trusted Publisher → GitHub Actions.
+2. Entregue valores exatos: organization/user, repository sem owner, filename (exemplo publish-npm.yml, **sem** .github/workflows/), environment igual ao job.
+3. Allowed actions deve corresponder ao workflow: publicação direta permite npm publish; staged publishing tem aprovação própria e não equivale a pacote publicado.
+4. Use runner GitHub hospedado, contents: read e id-token: write só no job publicador, com environment/refs protegidos. Confira requisitos atuais: baseline Node >=22.14 e npm >=11.5.1. Fixe versões suportadas, sem depender silenciosamente do npm do runner.
+5. OIDC não requer NPM_TOKEN/NODE_AUTH_TOKEN. Dependências privadas podem exigir credencial de leitura separada, só no install.
+6. Pacote ainda inexistente: confira bootstrap suportado atualmente. Não prometa Settings de pacote que não existe. Prepare primeira publicação pelo Actions com fallback granular autorizado quando necessário; depois configure trust e remova/revogue o token temporário. Nunca publique pacote de teste arbitrário nem execute npm publish local.
+
+## Fallback granular, quando necessário
+
+Explique por que OIDC não atende ao runner/registry/pacote. npm → avatar → Access Tokens → Generate New Token; nome para repo/ambiente, Read and write somente no pacote/scope selecionado, validade mínima adequada, sem acesso organizacional extra. Verifique Bypass 2FA exigido para publicação não interativa e política do pacote; não remova 2FA da conta. Usuário cola token diretamente no GitHub secret **NPM_TOKEN**, environment **npm**, nunca na conversa.
+
+Configure registry HTTPS correto e mapeie secrets.NPM_TOKEN para NODE_AUTH_TOKEN somente no passo necessário. .npmrc contém referência literal à variável, nunca o valor. Planeje rotação: confirme substituto antes de revogar anterior.
+
+## Qualificar, testar e observar
+
+- Build/testes, npm pack --dry-run, inspeção de arquivos, pack real, checksum e instalação/smoke do tarball limpo. Exclua .env, SSH, tokens e arquivos privados.
+- Build sem credencial de escrita. Revise lifecycle scripts; prefira publicar tarball preparado com --ignore-scripts quando compatível.
+- Combine pacote aprovado, versão inédita e canal explícito antes do teste real. Publicação npm é persistente mesmo com tag de teste. Não altere latest para diagnosticar.
+- O job confere tag/ref, manifesto, SHA e canal e publica o mesmo tarball validado. Use provenance quando os requisitos de pacote/repositório permitirem.
+- OIDC: id-token/trust presente ou dry-run não prova permissão de publish; npm whoami não valida esse grant. Fallback: teste autenticado read-only suportado prova somente autenticação; whoami pode exigir 2FA/política e não decide isoladamente validade de publicação.
+- Prova final: run bem-sucedido, pacote@versão no registry, dist-tag esperado, integridade igual ao tarball e instalação/smoke da versão exata. Staged aguardando aprovação permanece pendente.
+- 401/403: confira registry, validade, escopo/2FA e trust (owner, repo, filename, environment, allowed actions). Versão existente não é erro de token; não sobrescreva. Retry só considera recuperado após verificar integridade e canal.
+
+Fontes: [Trusted publishers](https://docs.npmjs.com/trusted-publishers/), [Criar token](https://docs.npmjs.com/creating-and-viewing-access-tokens/), [Publicar](https://docs.npmjs.com/cli/v11/commands/npm-publish/), [Provenance](https://docs.npmjs.com/generating-provenance-statements/).

package/templates/.agents/skills/zaip-skill-github-actions-setup/scripts/check-skill.mjs

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { parseDocument } from "../../zaip-skill-github-deploy/scripts/yaml-parser.mjs";
+
+const skill = resolve(import.meta.dirname, "..");
+const root = resolve(skill, "../../..");
+const read = (file) => readFileSync(file, "utf8");
+function yaml(source) {
+  const doc = parseDocument(source, { strict: true, uniqueKeys: true });
+  assert.equal(doc.errors.length, 0);
+  return doc.toJS();
+}
+const source = read(resolve(skill, "SKILL.md"));
+const meta = yaml(source.match(/^---\r?\n([\s\S]*?)\r?\n---/)[1]);
+assert.deepEqual(Object.keys(meta).sort(), ["description", "name"]);
+assert.equal(meta.name, "zaip-skill-github-actions-setup");
+assert.ok(source.split(/\r?\n/).length <= 120);
+const ui = yaml(read(resolve(skill, "agents/openai.yaml"))).interface;
+assert.ok(ui.default_prompt.includes("$" + meta.name));
+assert.ok(ui.short_description.length >= 25 && ui.short_description.length <= 64);
+
+const lock = yaml(read(resolve(root, ".agents/config/framework.lock.yaml")));
+const files = readdirSync(skill, { recursive: true, withFileTypes: true }).filter((e) =>
+  e.isFile(),
+);
+for (const entry of files) {
+  const file = resolve(entry.parentPath, entry.name);
+  const path = relative(root, file).replaceAll("\\", "/");
+  const text = read(file);
+  const hash = createHash("sha256").update(text.replaceAll("\r\n", "\n")).digest("hex");
+  assert.equal(lock.managed_files[path], hash, "managed content differs: " + path);
+  if (!path.endsWith(".md")) continue;
+  for (const match of text.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+    if (/^https:\/\//.test(match[1])) continue;
+    assert.ok(
+      existsSync(resolve(dirname(file), match[1].split("#")[0])),
+      "missing local resource: " + match[1],
+    );
+  }
+}
+const page = read(resolve(skill, "references/cloudflare-pages.md"));
+const steps = yaml(page.match(/```yaml\n([\s\S]*?)\n```/)[1]);
+assert.equal(steps.length, 1);
+assert.deepEqual(Object.keys(steps[0].env).sort(), [
+  "CLOUDFLARE_ACCOUNT_ID",
+  "CLOUDFLARE_API_TOKEN",
+  "CLOUDFLARE_PAGES_PROJECT",
+]);
+assert.equal(steps[0].env.CLOUDFLARE_API_TOKEN, "${{ secrets.CLOUDFLARE_API_TOKEN }}");
+assert.ok(existsSync(resolve(root, steps[0].run.slice("node ".length))));
+process.stdout.write(
+  "Skill metadata, local resources, executable YAML mapping and all managed checksums verified.\n",
+);

package/templates/.agents/skills/zaip-skill-github-actions-setup/scripts/verify-cloudflare.mjs

@@ -0,0 +1,61 @@
+import { pathToFileURL } from "node:url";
+
+// GET-only user-token probe. No credential arguments, redirects or response dumps.
+export async function verifyCloudflare(env = process.env, fetcher = globalThis.fetch) {
+  const token = env.CLOUDFLARE_API_TOKEN;
+  const account = env.CLOUDFLARE_ACCOUNT_ID;
+  const project = env.CLOUDFLARE_PAGES_PROJECT;
+  const result = {
+    credential: "unverified",
+    project_access: "unverified",
+    deployment: "unverified",
+  };
+  if (typeof token !== "string" || !token.trim() || /[\r\n]/.test(token)) {
+    return { ...result, error: "missing_or_invalid_CLOUDFLARE_API_TOKEN" };
+  }
+  if (!/^[a-fA-F0-9]{32}$/.test(account ?? "")) {
+    return { ...result, error: "invalid_CLOUDFLARE_ACCOUNT_ID" };
+  }
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,56}[a-z0-9])?$/.test(project ?? "")) {
+    return { ...result, error: "invalid_CLOUDFLARE_PAGES_PROJECT" };
+  }
+  let stage = "credential";
+  async function get(path) {
+    const response = await fetcher("https://api.cloudflare.com/client/v4" + path, {
+      method: "GET",
+      headers: { Authorization: "Bearer " + token, Accept: "application/json" },
+      redirect: "error",
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!response.ok) {
+      const status = Number.isInteger(response.status) ? response.status : "unknown";
+      return { error: stage + "_http_" + status };
+    }
+    const body = await response.json();
+    if (body?.success !== true || !body.result || typeof body.result !== "object") {
+      return { error: stage + "_invalid_response" };
+    }
+    return { value: body.result };
+  }
+  try {
+    const auth = await get("/user/tokens/verify");
+    if (auth.error) return { ...result, error: auth.error };
+    if (auth.value.status !== "active") return { ...result, error: "credential_not_active" };
+    result.credential = "verified";
+    stage = "project_access";
+    const access = await get("/accounts/" + account + "/pages/projects/" + project);
+    if (access.error) return { ...result, error: access.error };
+    if (access.value.name !== project) return { ...result, error: "project_identity_mismatch" };
+    result.project_access = "verified";
+    return result;
+  } catch {
+    // Fetch/parse exceptions can contain secrets or provider response text.
+    return { ...result, error: stage + "_transport_or_parse_error" };
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = await verifyCloudflare();
+  process.stdout.write(JSON.stringify(result) + "\n");
+  process.exitCode = result.error ? 1 : 0;
+}

package/templates/.agents/skills/zaip-skill-github-actions-setup/scripts/verify-cloudflare.test.mjs

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { verifyCloudflare } from "./verify-cloudflare.mjs";
+
+const secret = "synthetic-secret-do-not-log";
+const env = {
+  CLOUDFLARE_API_TOKEN: secret,
+  CLOUDFLARE_ACCOUNT_ID: "a".repeat(32),
+  CLOUDFLARE_PAGES_PROJECT: "demo-preview",
+};
+const response = (result, status = 200, success = true) => ({
+  ok: status === 200,
+  status,
+  json: async () => ({ success, result }),
+});
+function queue(...responses) {
+  const calls = [];
+  const fetcher = async (url, options) => {
+    calls.push({ url, options });
+    const next = responses.shift();
+    if (next instanceof Error) throw next;
+    assert.ok(next, "unexpected request");
+    return next;
+  };
+  return { calls, fetcher };
+}
+
+test("GET-only probe binds account/project, refuses redirects and does not claim deployment", async () => {
+  const q = queue(
+    response({ status: "active" }),
+    response({ name: env.CLOUDFLARE_PAGES_PROJECT, private_config: secret }),
+  );
+  assert.deepEqual(await verifyCloudflare(env, q.fetcher), {
+    credential: "verified",
+    project_access: "verified",
+    deployment: "unverified",
+  });
+  assert.equal(q.calls.length, 2);
+  assert.equal(
+    q.calls[1].url,
+    "https://api.cloudflare.com/client/v4/accounts/" +
+      "a".repeat(32) +
+      "/pages/projects/demo-preview",
+  );
+  for (const { options } of q.calls) {
+    assert.equal(options.method, "GET");
+    assert.equal(options.redirect, "error");
+    assert.equal(options.headers.Authorization, "Bearer " + secret);
+    assert.ok(options.signal instanceof AbortSignal);
+  }
+});
+
+for (const [key, value] of [
+  ["CLOUDFLARE_API_TOKEN", ""],
+  ["CLOUDFLARE_API_TOKEN", "token\ninjection"],
+  ["CLOUDFLARE_ACCOUNT_ID", "../other"],
+  ["CLOUDFLARE_PAGES_PROJECT", "project?account=other"],
+])
+  test("invalid input stops before network: " + key + "=" + JSON.stringify(value), async () => {
+    const q = queue();
+    const result = await verifyCloudflare({ ...env, [key]: value }, q.fetcher);
+    assert.ok(result.error);
+    assert.equal(q.calls.length, 0);
+  });
+
+test("expired token never probes project", async () => {
+  const q = queue(response({ status: "expired" }));
+  const result = await verifyCloudflare(env, q.fetcher);
+  assert.equal(result.error, "credential_not_active");
+  assert.equal(q.calls.length, 1);
+});
+
+for (const status of [401, 403, 404])
+  test("project HTTP " + status + " stays unverified with no provider body", async () => {
+    const q = queue(response({ status: "active" }), response({ name: secret }, status));
+    const result = await verifyCloudflare(env, q.fetcher);
+    assert.equal(result.credential, "verified");
+    assert.equal(result.project_access, "unverified");
+    assert.equal(result.error, "project_access_http_" + status);
+    assert.ok(!JSON.stringify(result).includes(secret));
+  });
+
+test("successful HTTP with API failure is not valid authentication", async () => {
+  const q = queue(response({ status: "active" }, 200, false));
+  assert.equal((await verifyCloudflare(env, q.fetcher)).credential, "unverified");
+});
+
+test("wrong project identity is rejected", async () => {
+  const q = queue(response({ status: "active" }), response({ name: "another-project" }));
+  assert.equal((await verifyCloudflare(env, q.fetcher)).error, "project_identity_mismatch");
+});
+
+for (const failure of [
+  new Error("network error " + secret),
+  {
+    ok: true,
+    status: 200,
+    json: async () => {
+      throw new Error(secret);
+    },
+  },
+])
+  test("transport/parse exceptions are sanitized", async () => {
+    const result = await verifyCloudflare(env, queue(failure).fetcher);
+    assert.equal(result.error, "credential_transport_or_parse_error");
+    assert.ok(!JSON.stringify(result).includes(secret));
+  });
+
+test("CLI rejects missing configuration with nonzero exit and sanitized output", () => {
+  const child = spawnSync(
+    process.execPath,
+    [fileURLToPath(new URL("./verify-cloudflare.mjs", import.meta.url))],
+    {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        CLOUDFLARE_API_TOKEN: "",
+        CLOUDFLARE_ACCOUNT_ID: env.CLOUDFLARE_ACCOUNT_ID,
+        CLOUDFLARE_PAGES_PROJECT: env.CLOUDFLARE_PAGES_PROJECT,
+      },
+    },
+  );
+  assert.equal(child.status, 1, child.stderr);
+  assert.equal(JSON.parse(child.stdout).error, "missing_or_invalid_CLOUDFLARE_API_TOKEN");
+  assert.equal(child.stderr, "");
+});

package/templates/.agents/skills/zaip-skill-github-actions-setup/scripts/verify-ssh.integration.test.mjs

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import test from "node:test";
+
+function findBash() {
+  if (process.platform !== "win32") return "bash";
+  const git = spawnSync("where.exe", ["git.exe"], { encoding: "utf8" });
+  const candidates = (git.stdout ?? "")
+    .trim()
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .flatMap((file) => [
+      resolve(dirname(file), "../bin/bash.exe"),
+      resolve(dirname(file), "../../bin/bash.exe"),
+    ]);
+  const match = candidates.find(existsSync);
+  assert.ok(match, "Git for Windows with Bash must be available on PATH for this integration test");
+  return match;
+}
+const bash = findBash();
+const guide = await readFile(new URL("../references/hostinger-vps.md", import.meta.url), "utf8");
+const snippet = guide.match(/```bash\n([\s\S]*?)\n```/)[1];
+const toPosix = (value) =>
+  process.platform === "win32"
+    ? value.replaceAll("\\", "/").replace(/^([A-Za-z]):/, (_, drive) => "/" + drive.toLowerCase())
+    : value;
+
+async function runProbe(overrides = {}) {
+  const dir = await mkdtemp(join(tmpdir(), "zaip-ssh-probe-"));
+  const stub = join(dir, "ssh");
+  // Execute the actual guide snippet, substituting only the external SSH process.
+  await writeFile(
+    stub,
+    '#!/usr/bin/env bash\nset -eu\nprintf "%s\\n" "$@" > "$PROBE_ARGS"\ntest -s "$4"\nprintf "%s" "$4" > "$PROBE_KEY_PATH"\nif env | grep -q "^VPS_SSH_PRIVATE_KEY="; then exit 99; fi\nexit "${PROBE_EXIT:-0}"\n',
+  );
+  await chmod(stub, 0o700);
+  const script = join(dir, "probe.sh");
+  await writeFile(script, 'export PATH="' + toPosix(dir) + ':$PATH"\n' + snippet);
+  const argsFile = join(dir, "args.txt");
+  const keyPathFile = join(dir, "key-path.txt");
+  const child = spawnSync(bash, [toPosix(script)], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      VPS_HOST: "example.invalid",
+      VPS_PORT: "2222",
+      VPS_USER: "deploy",
+      VPS_SSH_PRIVATE_KEY: "synthetic-multiline\nprivate-key",
+      VPS_KNOWN_HOSTS: "[example.invalid]:2222 ssh-ed25519 synthetic-public",
+      PROBE_ARGS: toPosix(argsFile),
+      PROBE_KEY_PATH: toPosix(keyPathFile),
+      ...overrides,
+    },
+  });
+  let args = null;
+  try {
+    args = await readFile(argsFile, "utf8");
+  } catch {}
+  let cleanupExit = null;
+  try {
+    const keyPath = await readFile(keyPathFile, "utf8");
+    cleanupExit = spawnSync(bash, [
+      "-c",
+      'test ! -e "$1" && test ! -d "$(dirname "$1")"',
+      "--",
+      keyPath,
+    ]).status;
+  } catch {}
+  assert.equal(dirname(resolve(dir)), resolve(tmpdir()));
+  assert.ok(basename(dir).startsWith("zaip-ssh-probe-"));
+  await rm(dir, { recursive: true, force: true });
+  return { ...child, args, cleanupExit };
+}
+
+test("guide SSH test uses verified host, fixed read-only command and cleans key", async () => {
+  const result = await runProbe();
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.args, /StrictHostKeyChecking=yes/);
+  assert.match(result.args, /BatchMode=yes/);
+  assert.match(result.args, /deploy@example.invalid\ntrue\n$/);
+  assert.equal(result.cleanupExit, 0);
+  assert.ok(!result.stdout.includes("private-key"));
+});
+
+test("SSH failure is propagated and private material removed", async () => {
+  const result = await runProbe({ PROBE_EXIT: "255" });
+  assert.equal(result.status, 255, result.stderr);
+  assert.equal(result.cleanupExit, 0);
+});
+
+for (const fields of [
+  { VPS_HOST: "-oProxyCommand=bad" },
+  { VPS_USER: "deploy;bad" },
+  { VPS_PORT: "0" },
+  { VPS_PORT: "65536" },
+  { VPS_PORT: "22;bad" },
+])
+  test("invalid SSH destination never executes SSH: " + JSON.stringify(fields), async () => {
+    const result = await runProbe(fields);
+    assert.equal(result.status, 2, result.stderr);
+    assert.equal(result.args, null);
+  });