rbin-task-flow 1.25.0 → 1.25.1

package/.claude/skills/rbin-coding-standards/SKILL.md

@@ -13,9 +13,10 @@ paths: ["src/**", "app/**"]
 
 1. Apply the **checklist** in `.cursor/rules/coding_standards.mdc` (default for all implementation). Do **not** read the entire `.mdc` or full markdown into context if the checklist already covers the task.
 2. Implement using checklist rules: `app/` thin, `features/`, `shared/`, service+use-case, RHF+zod+`Controller`, `cn()`, no `any`, no raw base UI.
-3. **Only if ambiguous** (Nest gateways, DataHandler, route groups, naming edge case): open **one or two sections** of `.task-flow/guides/coding-standards-full.md` — never paste or load the whole file.
-4. If `graphify-out/graph.json` exists, `graphify query` before choosing file paths for new code.
-5. No explanatory code comments; use `dev-logs/` for non-obvious design notes.
+3. **Vercel projects:** env files per **Vercel — environment variables** in `coding-standards-full.md` (§0–§8).
+4. **Only if ambiguous** (Nest gateways, DataHandler, route groups, naming edge case): open **one or two sections** of `.task-flow/guides/coding-standards-full.md` — never paste or load the whole file.
+5. If `graphify-out/graph.json` exists, `graphify query` before choosing file paths for new code.
+6. No explanatory code comments; use `dev-logs/` for non-obvious design notes.
 
 ## Token discipline
 

package/.claude/skills/rbin-coding-standards/reference.md

@@ -6,6 +6,7 @@
 |-----|------|------|
 | **Checklist** (default) | `.cursor/rules/coding_standards.mdc` | Every implementation; glob on `src/**`, `app/**` in Cursor |
 | **Full reference** (sections only) | `.task-flow/guides/coding-standards-full.md` | Nest/Prisma detail, long examples, ESLint table, DataHandler, providers |
+| **Vercel `.env`** | `coding-standards-full.md` § Vercel | Projects on Vercel — 3 mirrored env files + sync scripts |
 
 ## Checklist essentials
 
@@ -40,3 +41,4 @@
 | Context / Auth Hook | Auth provider pattern |
 | Testing | E2E placement |
 | Critical Rules | Final verification |
+| Vercel — environment variables | `.env` setup on Vercel deploys → open this section in full doc |

package/.cursor/rules/coding_standards.mdc

@@ -84,6 +84,18 @@ src/
 
 ---
 
+## Vercel — `.env` (when project deploys on Vercel)
+
+Follow **Vercel — environment variables** in [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) (§0–§8):
+
+- **3 mirrored files:** `.env.example` (committed, empty values), `.env.local` (dev), `.env.production` (synced to Vercel).
+- Same keys, **alphabetical order**, one var per line — no section comments breaking alignment.
+- `.gitignore`: `.env`, `.env.*`, `!.env.example`.
+- Scripts: `scripts/env-files-check.sh`, `scripts/vercel-env-sync.sh` (full content in full doc §5–§6).
+- Audit orphan vars before aligning; classify `NEXT_PUBLIC_*`/flags as plaintext, rest as secret on Vercel.
+
+---
+
 ## Audit / sync
 
 - **`task-flow: audit`:** score against this checklist; open [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) only for deep dives or user-requested depth.
@@ -97,4 +109,5 @@ src/
 |------|-----|
 | Implementing code | `@rbin-coding-standards` |
 | Full examples / Nest / gateways | Sections of `coding-standards-full.md` |
+| Vercel `.env` setup | `coding-standards-full.md` § Vercel |
 | Audit all categories | `@task-flow-audit` |

package/.task-flow/README.md

@@ -14,7 +14,7 @@
     ├── AI-PLATFORMS.md
     ├── GRAPHIFY.md
     ├── CODEX.md · CURSOR.md
-    ├── coding-standards-full.md
+    ├── coding-standards-full.md  ← inclui padrão .env Vercel (§ Vercel)
     ├── platforms/         ← Claude, Cursor, Codex
     └── reports/           ← task-X-implementation.md
 ```
@@ -31,7 +31,7 @@
 | Codex workflows | [guides/CODEX.md](guides/CODEX.md) |
 | Cursor quick ref | [guides/CURSOR.md](guides/CURSOR.md) |
 | Otimização (tokens) | [guides/OPTIMIZATION-PLAN.md](guides/OPTIMIZATION-PLAN.md) |
-| Coding standards (full) | [guides/coding-standards-full.md](guides/coding-standards-full.md) |
+| Coding standards (full) | [guides/coding-standards-full.md](guides/coding-standards-full.md) (Vercel `.env` no topo) |
 
 ## 🚀 Quick Commands
 

package/.task-flow/guides/coding-standards-full.md

@@ -8,6 +8,151 @@ These rules define how code MUST be written when implementing tasks. Always foll
 
 ---
 
+## Vercel — environment variables
+
+**When the project deploys on Vercel** (Next.js, etc.), follow this section for `.env` files.
+
+### Instruções para a IA (executar nesta ordem)
+
+1. **Antes de tudo — auditar variáveis sem uso** [§0]: para cada variável dos `.env*`, verifique se ela é realmente referenciada no código/configuração. **Liste as órfãs e confirme com o usuário antes de remover** — não apague sozinha (algumas são usadas só em runtime/CI/infra). Só depois de limpar é que se alinham os 3 arquivos.
+2. Crie `scripts/env-files-check.sh` e `scripts/vercel-env-sync.sh` com **exatamente** o conteúdo das seções [§5] e [§6]. Marque ambos como executáveis (`chmod +x`).
+3. Garanta os **3 arquivos de ambiente** seguindo a convenção [§1]: mesma sequência de chaves nos 3, **ordem alfabética**, uma variável por linha, sem comentários de seção no meio. Crie `.env.example` (commitado, valores vazios). **Nunca** coloque valores reais no `.env.example`.
+4. Ajuste o `.gitignore` conforme [§2].
+5. Ajuste a `PLAINTEXT_REGEX` do `vercel-env-sync.sh` ao stack do projeto [§3].
+6. Rode `./scripts/env-files-check.sh` e mostre a saída. Não rode o sync da Vercel sem credenciais do usuário — explique os comandos de [§4].
+7. Confirme os **critérios de aceite** [§7].
+
+### §0 — Auditoria (variáveis sem uso)
+
+Para cada chave dos `.env*`, procure referências: `process.env.NOME`, `import.meta.env.NOME`, `env("NOME")`, configs/CI (`vercel.json`, `*.yml`, `Dockerfile`).
+
+```bash
+for k in $(grep -hE '^[A-Za-z_][A-Za-z0-9_]*=' .env.example .env.local .env.production 2>/dev/null \
+            | sed -E 's/=.*//' | sort -u); do
+  n=$(grep -rIn --exclude-dir=node_modules --exclude-dir=.git --exclude='.env*' \
+        -e "$k" . 2>/dev/null | wc -l | tr -d ' ')
+  printf '%-32s %s ref(s)\n' "$k" "$n"
+done
+```
+
+**Trate `0 ref` como candidata, não certeza.** Confirme com o usuário antes de remover.
+
+### §1 — Convenção dos 3 arquivos
+
+| Arquivo | Commitado? | Papel | Valores |
+|---|---|---|---|
+| `.env.example` | ✅ sim | Lista canônica (doc) | vazios/placeholder |
+| `.env.local` | ❌ não | Desenvolvimento local | reais de dev |
+| `.env.production` | ❌ não | **Sincronizado com a Vercel** | reais de produção |
+
+Mesma sequência de chaves, **ordem alfabética**. Sem comentários de seção no meio.
+
+### §2 — `.gitignore`
+
+```gitignore
+.env
+.env.*
+!.env.example
+```
+
+### §3 — Classificação secret × plaintext (Vercel)
+
+| Classe | Exemplos | Tipo |
+|---|---|---|
+| `NEXT_PUBLIC_*` | `NEXT_PUBLIC_API_URL` | **plaintext** |
+| Flags / URLs públicas | `*_ENABLED`, `*_PUBLIC_URL`, `NODE_ENV` | **plaintext** |
+| Todo o resto | `*_API_KEY`, `*_SECRET`, `*_TOKEN` | **secret** (`--sensitive`) |
+
+### §4 — Comandos
+
+```bash
+npm i -g vercel && vercel login && vercel link
+./scripts/env-files-check.sh
+DRY_RUN=1 ./scripts/vercel-env-sync.sh
+./scripts/vercel-env-sync.sh
+vercel env pull .env.vercel.check --environment=production
+```
+
+### §5 — `scripts/env-files-check.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+if [ "$#" -gt 0 ]; then FILES=("$@"); else FILES=(".env.example" ".env.local" ".env.production"); fi
+keys_of() { grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$1" | sed -E 's/=.*//'; }
+fail=0; ref=""; ref_file=""
+for f in "${FILES[@]}"; do
+  if [ ! -f "$f" ]; then echo "❌ faltando: $f"; fail=1; continue; fi
+  keys="$(keys_of "$f")"
+  sorted="$(printf '%s\n' "$keys" | LC_ALL=C sort)"
+  if [ "$keys" != "$sorted" ]; then
+    echo "❌ $f não está em ordem alfabética."
+    diff <(printf '%s\n' "$keys") <(printf '%s\n' "$sorted") | head -6
+    fail=1
+  fi
+  count="$(printf '%s\n' "$keys" | grep -c . || true)"
+  echo "• $f — $count variáveis"
+  if [ -z "$ref" ]; then ref="$sorted"; ref_file="$f"
+  elif [ "$sorted" != "$ref" ]; then
+    echo "❌ $f difere de $ref_file:"
+    diff <(printf '%s\n' "$ref") <(printf '%s\n' "$sorted") || true
+    fail=1
+  fi
+done
+if [ "$fail" -eq 0 ]; then echo "✅ Arquivos alinhados, mesma sequência e em ordem alfabética."
+else echo "→ Corrija as divergências acima."; fi
+exit "$fail"
+```
+
+### §6 — `scripts/vercel-env-sync.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+ENV_FILE="${1:-.env.production}"
+TARGET="${2:-production}"
+DRY_RUN="${DRY_RUN:-0}"
+PLAINTEXT_REGEX="${PLAINTEXT_REGEX:-^(NEXT_PUBLIC_|NODE_ENV$|.*_ENABLED$|.*_URL_STRATEGY$|.*_PUBLIC_URL$|.*_REGION$)}"
+command -v vercel >/dev/null 2>&1 || { echo "❌ vercel CLI não encontrado. Instale: npm i -g vercel"; exit 1; }
+[ -f "$ENV_FILE" ] || { echo "❌ arquivo não encontrado: $ENV_FILE"; exit 1; }
+[ -d ".vercel" ] || echo "⚠️  projeto não vinculado — rode 'vercel link' antes (continuando…)"
+secret_count=0; plain_count=0
+while IFS= read -r line <&3 || [ -n "$line" ]; do
+  case "$line" in ''|\#*) continue ;; esac
+  case "$line" in *=*) ;; *) continue ;; esac
+  key="${line%%=*}"; val="${line#*=}"
+  key="$(printf '%s' "$key" | tr -d '[:space:]')"
+  val="${val%\"}"; val="${val#\"}"; val="${val%\'}"; val="${val#\'}"
+  [ -z "$key" ] && continue
+  if [ -z "$val" ]; then echo "⏭️  $key (valor vazio — pulado)"; continue; fi
+  if printf '%s' "$key" | grep -Eq "$PLAINTEXT_REGEX"; then
+    flag=""; kind="plaintext"; plain_count=$((plain_count+1))
+  else
+    flag="--sensitive"; kind="secret  "; secret_count=$((secret_count+1))
+  fi
+  echo "→ [$kind] $key  ($TARGET)"
+  [ "$DRY_RUN" = "1" ] && continue
+  vercel env rm "$key" "$TARGET" -y </dev/null >/dev/null 2>&1 || true
+  printf '%s' "$val" | vercel env add "$key" "$TARGET" $flag >/dev/null
+done 3< "$ENV_FILE"
+echo "✅ $secret_count secret(s), $plain_count plaintext em '$TARGET'."
+[ "$DRY_RUN" = "1" ] && echo "(DRY_RUN — nada foi enviado)"
+```
+
+### §7 — Critérios de aceite
+
+- Auditoria [§0] feita; órfãs removidas após confirmação do usuário.
+- Scripts executáveis; 3 arquivos com mesma sequência alfabética.
+- `./scripts/env-files-check.sh` retorna exit 0.
+- `.gitignore` ignora `.env*` exceto `.env.example`.
+- Nenhum valor real no `.env.example` nem no git.
+
+### §8 — Limitações
+
+Valores multilinha (PEM/JSON) → base64 numa linha ou cadastro manual na Vercel. `NEXT_PUBLIC_*` no target do **build**.
+
+---
+
 ## Project Structure
 
 All projects use TypeScript and follow this structure:

package/README.md

@@ -33,7 +33,7 @@
 <a id="português"></a>
 # 🇧🇷 Português
 
-> **v1.25.0** — `.task-flow/` enxuto: tasks na raiz, docs em `guides/`. De **1.24.x**: `npm install -g rbin-task-flow@1.25` e `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Publicação](RELEASE-1.25.0.md).
+> **v1.25.1** — Padrão `.env` Vercel nos coding standards. De **1.25.0**: `npm install -g rbin-task-flow@1.25.1` e `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Publicação](RELEASE-1.25.1.md).
 
 ## O Que É Este Projeto?
 
@@ -419,7 +419,7 @@ Para problemas ou perguntas:
 <a id="english"></a>
 # 🇬🇧 English
 
-> **v1.25.0** — Slim `.task-flow/`: tasks at root, docs in `guides/`. From **1.24.x**: `npm install -g rbin-task-flow@1.25` then `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Release guide](RELEASE-1.25.0.md).
+> **v1.25.1** — Vercel `.env` pattern in coding standards. From **1.25.0**: `npm install -g rbin-task-flow@1.25.1` then `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Release guide](RELEASE-1.25.1.md).
 
 ## What Is This Project?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rbin-task-flow",
-  "version": "1.25.0",
+  "version": "1.25.1",
   "description": "AI-powered task management for Claude and Cursor",
   "main": "index.js",
   "bin": {