@fontdata/ai-harness 2.0.0 → 2.2.0

package/templates/commands/configurar-auto-tag.md

@@ -1,185 +0,0 @@
----
-description: Detecta o padrão de versionamento do projeto (qualquer stack, inclusive Delphi) e gera a GitHub Action que cria a tag automaticamente quando a versão chega na main. Separa versionar (humano) de taguear/deployar (automático).
-argument-hint: "[branch-de-producao]"
----
-
-# /configurar-auto-tag — Auto-tag no merge para a branch de produção
-
-Você vai **configurar a automação de tag** deste repositório: descobrir **como o versionamento já funciona
-aqui** (Node/JS-TS, .NET, Delphi, Flutter, Python, arquivo `VERSION`, etc.) e gerar uma **GitHub Action** que
-**cria a tag automaticamente** quando um novo número de versão chega na branch de produção (`main` por padrão).
-
-O objetivo é separar dois papéis:
-
-- **Versionar** — ação humana (o comando `/versao`), com aprovação de versão e changelog. **Sem tag, sem push.**
-- **Taguear/deployar** — ação automática (esta Action), disparada quando o arquivo de versão muda na `main`.
-
-A **tag é a fonte única do release** e a criação é **idempotente** por versão (nunca recria uma tag existente).
-
-> **🚦 Há um GATE de aprovação obrigatório** antes de escrever qualquer arquivo. Este comando **não faz push**
-> e **não cria tags manualmente** — ele só instala a automação e a documentação.
-
-## Uso
-
-- `/configurar-auto-tag` — usa `main` como branch de produção.
-- `/configurar-auto-tag <branch>` — usa a branch informada (ex.: `master`, `release`) como alvo da tag.
-
-## Passo 0 — Pré-checagem (somente leitura)
-
-1. Confirme que é um repositório git com remoto no **GitHub** (`git remote -v`). Se não for GitHub, avise que
-   a Action de GitHub Actions não se aplica e **pergunte** como o usuário quer prosseguir (GitLab CI, etc.).
-2. Descubra a **branch de produção** real: use o argumento, senão a branch padrão do remoto
-   (`git symbolic-ref --short refs/remotes/origin/HEAD` ou olhe `main`/`master`). **Confirme com o usuário.**
-3. Verifique se já existe `.github/workflows/auto-tag.yml`. Se existir, leia e trate como **ajuste**, não
-   sobrescrita cega.
-
-## Passo 1 — Detectar a(s) fonte(s) de verdade da versão
-
-Investigue o projeto e **identifique TODAS as fontes da versão** (não assuma; confirme lendo). Para cada uma,
-registre: o **arquivo**, o **campo/chave**, o **formato** (`X.Y.Z` ou `X.Y.Z.W`) e **como extrair a versão via
-shell** (você vai embutir isso na Action). Por stack:
-
-- **Node / React (Vite/Next) / qualquer JS-TS:** `package.json` → campo `.version`.
-  - Extração: `jq -r '.version' package.json`
-  - Mobile Expo: `app.json` → `.expo.version` (`jq -r '.expo.version' app.json`).
-- **.NET / C#:** `*.csproj` (`<Version>`, senão `<FileVersion>`), `Directory.Build.props`.
-  - Extração: `grep -oPm1 '(?<=<Version>)[^<]+' App.csproj` (ajuste a tag lida).
-- **Delphi:** o número costuma viver no `*.dproj` (chaves `VerInfo_Keys` com `FileVersion`/`ProductVersion` e/ou
-  os campos `MajorVersion`/`MinorVersion`/`Release`/`Build`) **e/ou** em constante `.pas` (ex.: `cVersao`, `About`).
-  Escolha **uma** fonte estável como canônica e leia o **arquivo:linha** exato.
-  - Extração de `FileVersion` no `.dproj`: `grep -oPm1 'FileVersion=\K[0-9.]+' Projeto.dproj`
-  - Ou montando de partes: leia `MajorVersion`/`MinorVersion`/`Release`/`Build` com `grep`/`sed` e concatene.
-  - Ou de constante `.pas`: `grep -oPm1 "cVersao\s*=\s*'\K[0-9.]+" Sobre.pas`
-- **Flutter / Dart:** `pubspec.yaml` → `version:` (`grep -oPm1 '(?<=^version: )[0-9.+]+' pubspec.yaml`).
-- **Python:** `pyproject.toml` (`[project] version`/`[tool.poetry] version`) ou `__version__`.
-  - Extração: `grep -oPm1 '(?<=^version = ")[^"]+' pyproject.toml`.
-- **Genérico:** arquivo `VERSION` na raiz (`cat VERSION`), constante `VERSION`/`APP_VERSION`.
-
-> Se não encontrar nenhuma fonte de versão, **pergunte ao usuário** onde a versão é registrada antes de gerar a
-> Action — sem isso a Action não tem o que ler.
-
-Determine ainda:
-
-- **Repo único ou monorepo/multi-app.** Isso define o **formato da tag**:
-  - App único → tag `v<versão>` (ex.: `v1.4.0`).
-  - Monorepo → tag `<app>-v<versão>` (ex.: `web-v1.4.0`), com um arquivo de versão por app.
-- **Comando `/versao` já instalado?** Se sim, é ele quem faz o bump. Se não, sugira instalá-lo/rodá-lo para
-  produzir o commit de release que dispara esta Action.
-- **Como o deploy de produção é disparado** por cada tag (`deploy-*.yml` no GitHub Actions? webhook de app
-  externo tipo Expo/EAS?). Isso decide se o `RELEASE_PAT` é necessário (veja Passo 4).
-
-## Passo 2 — Montar a Action (rascunho, sem gravar ainda)
-
-Gere `.github/workflows/auto-tag.yml` seguindo este molde, **adaptando a extração da versão** à fonte detectada:
-
-```yaml
-name: Auto-tag na <BRANCH_PRODUCAO>
-
-on:
-  push:
-    branches: [<BRANCH_PRODUCAO>]
-    paths:
-      - <ARQUIVO(S)_DE_VERSAO>   # ex.: 'package.json' ou 'apps/**/package.json' ou 'src/Projeto.dproj'
-
-permissions:
-  contents: write
-
-jobs:
-  auto-tag:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.RELEASE_PAT || github.token }}
-
-      - name: Criar tag se a versão for nova
-        run: |
-          set -euo pipefail
-          # >>> AJUSTE a linha abaixo para extrair a versão da fonte de verdade detectada <<<
-          VERSION="$(jq -r '.version' package.json)"
-          if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then
-            echo "Não consegui ler a versão"; exit 1
-          fi
-          TAG="v$VERSION"            # monorepo: TAG="<app>-v$VERSION"
-          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
-            echo "Tag $TAG já existe — nada a fazer (idempotente)."
-            exit 0
-          fi
-          git config user.name  "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "$TAG" -m "Release $TAG"
-          git push origin "$TAG"
-```
-
-Regras ao adaptar o molde:
-
-- **Substitua `<BRANCH_PRODUCAO>`** pela branch confirmada no Passo 0.
-- **`paths:`** deve listar **exatamente** o(s) arquivo(s) de versão detectados — assim a Action só roda quando a
-  versão muda de fato, não a cada push.
-- **Troque a linha de `VERSION=`** pela extração correta da stack (jq/grep/sed/cat conforme o Passo 1). Para
-  Delphi/.NET, use o `grep -oP`/`sed` adequado ao XML/`.pas`; **não** use `jq` fora de JSON.
-- **Monorepo:** faça um loop pelos apps (uma tag por app), lendo a versão de cada arquivo e montando
-  `<app>-v<versão>`, com a checagem de idempotência por tag dentro do loop.
-- **Idempotência:** a verificação `git rev-parse --verify refs/tags/$TAG` é obrigatória — nunca recrie tag.
-- Se a Action já existia, **preserve** ajustes locais e só reconcilie o necessário.
-
-## Passo 3 — 🚦 GATE de aprovação (obrigatório)
-
-Antes de escrever qualquer arquivo, apresente ao usuário:
-
-- a **branch de produção** e o **formato de tag** escolhidos (`v<versão>` ou `<app>-v<versão>`);
-- a(s) **fonte(s) de versão** e a **linha de extração** que vai para a Action;
-- o **conteúdo completo** do `auto-tag.yml` proposto;
-- se **`RELEASE_PAT`** será necessário (Passo 4) e por quê.
-
-**Peça aprovação explícita.** Não grave nada sem o "ok".
-
-## Passo 4 — Documentar o `RELEASE_PAT` (não crie segredo no código)
-
-Explique ao usuário, e registre na doc do Passo 5, a **pegadinha do token**:
-
-- O **`GITHUB_TOKEN` padrão NÃO dispara outras Actions.** Se o deploy de produção é uma **GitHub Action**
-  (`deploy-*.yml`) disparada pela criação da tag, a Action de auto-tag **precisa** empurrar a tag usando um
-  **`RELEASE_PAT`** (por isso o `token: ${{ secrets.RELEASE_PAT || github.token }}` no checkout).
-- Se o deploy é disparado por **webhook de app externo** (ex.: Expo/EAS), o PAT é **desnecessário**.
-- Como criar: **fine-grained PAT** com _Contents: Read and write_ no repositório (ou classic com escopo `repo`),
-  salvo em **Settings → Secrets and variables → Actions** como **`RELEASE_PAT`**.
-- **Nunca** coloque o token em arquivo versionado — só como secret do repositório.
-
-## Passo 5 — Gravar artefatos (somente após aprovação)
-
-1. Escreva `.github/workflows/auto-tag.yml`.
-2. Crie/atualize `docs/versionamento-tags.md` explicando:
-   - que **a tag aponta um commit, não uma branch** — o commit do release (com os workflows de deploy) precisa
-     estar na branch de produção **antes/junto** da criação da tag;
-   - o **fluxo completo** de release (abaixo);
-   - o funcionamento da Action e a **pegadinha `GITHUB_TOKEN` × `RELEASE_PAT`**;
-   - uma **tabela**: app → arquivo de versão → formato da tag → workflow de deploy disparado.
-3. Se houver comandos/docs antigos que mandavam **criar tag** ou **dar push de tag** manualmente, ajuste-os para
-   o novo fluxo (a tag agora é responsabilidade exclusiva da Action).
-
-### Fluxo de release resultante (documente assim)
-
-```
-/versao  →  push do commit de release  →  merge/entrega na branch de produção
-        →  Action auto-tag cria a tag  →  workflow de deploy dispara pela tag  →  produção
-```
-
-## Passo 6 — Verificar e finalizar (sem push)
-
-- Valide a sintaxe YAML do workflow (indentação, `on.push.paths`, `permissions`).
-- **Não** rode `git push` e **não** crie tags manualmente. Deixe as alterações prontas (working tree) e informe
-  o fluxo manual de commit/push ao usuário — ou, se o `/git-commit-push` estiver instalado, sugira usá-lo.
-- Sugira um commit semântico como `chore: Configura auto-tag na <branch> via GitHub Actions`.
-
-## Guardrails
-
-- **NUNCA** `git push`; **NUNCA** crie tag local — a tag é responsabilidade exclusiva da Action.
-- **Sempre** confirmar branch, fonte de versão e o YAML no GATE antes de gravar.
-- **Replicar o padrão do projeto** (formato de versão e de tag) — nunca impor um novo.
-- **Idempotência**: a Action nunca recria uma tag existente; para refazer deploy, use o gatilho manual do
-  workflow de deploy, não recrie a tag.
-- **`main`/branch de produção = deploy de produção** — trate-a como produção.
-- Sem `RELEASE_PAT`, tags criadas pelo `GITHUB_TOKEN` **não** disparam outras Actions de deploy; documente isso.
-- Documentação em **pt-BR**.