enable-octane-swoole

Files (3)

• SKILL.md
• migration-steps.md · rules/
• rollback.md · rules/

SKILL.md (first lines)

# Enable Octane Swoole (Migração Opt-in)

## Consistency First

Esta skill é **só para projetos EXISTENTES em PHP-FPM** (`docker-stack-fpm` aplicada). Para projetos novos, rode `init-project` com perfil Octane direto. Não usar em greenfield.

A migração troca a base image (`php:8.4-fpm-bookworm` → `phpswoole/swoole:php8.4`), o comando do `app` (FPM → `octane:start`), o `proxy_pass` do Nginx (`fastcgi_pass:9000` → `proxy_pass:8000`), o healthcheck, e adiciona env vars Octane. Dados, migrations e código de aplicação não são tocados.

Branch git de backup e `.bak` em arquivos sobrescritos são obrigatórios. Compose customizado (sem header de geração do kit) **não** é sobrescrito automaticamente — gera diff para edição manual.

## Quick Reference

- Detecção: aborta se já é Octane (idempotente) ou se não é FPM canônico.
- Backup: branch `octane-migration-YYYYMMDD-HHMMSS` + `.bak` nos arquivos sobrescritos.
- Templates origem: `docker-stack-octane-swoole/templates/`.
- Pacote Composer: `laravel/octane` + `php artisan octane:install --server=swoole`.
- Middleware: `Laravel\Octane\Middleware\InvokeCachedRoutes` em `bootstrap/app.php`.
- Env vars adicionadas: `OCTANE_SERVER=swoole`, `OCTANE_HTTPS=true`, `OCTANE_MAX_REQUESTS=500`, `OCTANE_WATCH=false`.
- CI: ajustar `ci.yml` para refletir nova base (Node/PHP iguais; só muda o ext-swoole no `setup-php`).
- Revisão obrigatória contra `docker-stack-octane-swoole/rules/octane-safety-checklist.md` antes de subir produção.

## Workflow

- [ ] Detectar estado atual:

```bash
if grep -qE '^OCTANE_SERVER=swoole' .env 2>/dev/null; then
  echo "Projeto já em Octane Swoole. Nada a fazer."
  exit 0
fi

if ! grep -qE 'fastcgi_pass' docker/nginx/default.conf 2>/dev/null; then
  echo "ERRO: docker/nginx/default.conf não tem fastcgi_pass. Esta skill só migra de docker-stack-fpm."
  exit 1
fi
```

- [ ] Confirmar working tree limpa e criar branch de backup:

```bash
git diff --quiet || { echo "ERRO: working tree sujo. Commit/stash antes."; exit 1; }
BRANCH="octane-migration-$(date +%Y%m%d-%H%M%S)"
git checkout -b "$BRANCH"
```

- [ ] Backup `.bak` dos arquivos a sobrescrever e aplicação dos templates Octane (`Dockerfile`, `nginx-default.conf`, `octane-entrypoint.sh`, sed no `docker-compose.yml`): procedimento completo em `rules/migration-steps.md`. A skill aborta com diff e exige merge manual se `docker-compose.yml` perdeu o header `# generated by docker-stack-fpm`.

- [ ] Instalar Octane:

```bash
vendor/bin/sail composer require laravel/octane
vendor/bin/sail artisan octane:install --server=swoole --no-interaction
```

- [ ] Registrar middleware em `bootstrap/app.php`:

```php
// dentro de ->withMiddleware(function (Middleware $middleware) {
$middleware->prepend(\Laravel\Octane\Middleware\InvokeCachedRoutes::class);
```

- [ ] Append idempotente das env vars Octane:

```bash
set_env_entry() {
  local ENV_FILE="$1" ENTRY="$2" KEY_NAME="${ENTRY%%=*}"
  if grep -q "^${KEY_NAME}=" "$ENV_FILE"; then
    sed -i "s|^${KEY_NAME}=.*|${ENTRY}|" "$ENV_FILE"
  else
    echo "$ENTRY" >> "$ENV_FILE"
  fi
}

for ENTRY in "OCTANE_SERVER=swoole" "OCTANE_HTTPS=true" "OCTANE_MAX_REQUESTS=500" "OCTANE_WATCH=false"; do
  for ENV_FILE in .env .env.example; do
    [[ -f "$ENV_FILE" ]] && set_env_entry "$ENV_FILE" "$ENTRY"
  done
done
```

- [ ] Atualizar CI para refletir a nova base:

```bash
if [[ -f .github/workflows/ci.yml ]]; then
  grep -q "extensions:" .github/workflows/ci.yml && \
    sed -i "s/extensions: \(.*\)/extensions: \1, swoole/" .github/workflows/ci.yml
  python3 -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))" && echo "CI YAML válido."
fi
```

- [ ] Gerar relatório de packages para revisão:

```bash
vendor/bin/sail composer show --installed --format=text > octane-packages-report.txt
echo ""
echo "=== REVISÃO MANUAL OBRIGATÓRIA ==="
echo "Compare octane-packages-report.txt contra:"
echo "  .agents/skills/docker-stack-octane-swoole/rules/octane-safety-checklist.md"
echo "Procure singletons, static state e container leaks. Não suba sem revisar."
```

- [ ] Rebuild e smoke test:

```bash
vendor/bin/sail down
vendor/bin/sail build --no-cache app
vendor/bin/sail up -d
sleep 5
curl -fsSk https://localhost/ >/dev/null && echo "OK: Octane respondeu" || { echo "FAIL: ver logs"; vendor/bin/sail logs app | tail -50; }
```

- [ ] Rollback (se necessário): seguir `rules/rollback.md` (rollback rápido descartando branch ou rollback dentro da branch preservando histórico).

## Anti-Patterns

| Racionalização | Realidade |
| --- | --- |
| "Rodo em projeto greenfield." | Use `init-project` + `docker-stack-octane-swoole` direto. Esta skill é para projetos com estado em produção. |
| "Pulo o backup; está tudo no git." | Working tree sujo, `.env` não versionado, dados de dev locais — todos sumem sem `.bak`. Backup é obrigatório. |

From CoringaWc/ai-first-kit, MIT.

More from CoringaWc/ai-first-kit