Requisição 133 — Emissão Condicional de Cookies em Modo de Desenvolvimento, Comandos CLI de Gestão de Ambiente (env), Autenticação (auth:cookie) e Inspeção Headless (page:inspect)

• Status do intake: ready-for-intake

• Data: 2026-08-26

• Origem: relatório de operação de agentes de IA em conn2flow-ai-workspace/sdd/human-requests/req-020.md

• Classificação: cli, auth, environment, cookies, inspect, testing, developer-experience

• Batch candidato: BATCH-135

Esta especificação define os requisitos para dotar o framework conn2flow e sua interface de linha de comando (c2f) de ferramentas nativas para autenticação automatizada de agentes, alternância de ambiente de desenvolvimento/produção, inspeção visual headless de telas em runtime e emissão segura condicional de cookies de sessão.

1. Emissão Condicional e Segura de Cookies (gestor_cookie_is_secure())

• Problema Identificado:

  • No núcleo do sistema (gestor.php, gestor/bibliotecas/gestor.php, gestor/bibliotecas/usuario.php), a chamada setcookie() utiliza 'secure' => true de forma fixa.

  • No ambiente local (http://localhost/ ou http://[REDACTED]/), clientes de terminal (curl, Node, scripts de automação) descartam os cookies Set-Cookie com atributo Secure em conexões HTTP não-criptografadas, impossibilitando a persistência de sessão e bloqueando requisições automatizadas para rotas autenticadas do Gestor.

• Solução Requerida:

  • Implementar a função pura e centralizada gestor_cookie_is_secure(): bool em gestor/bibliotecas/gestor.php.

  • Regras de Avaliação de Segurança (Defesa em Profundidade / Fail-Secure):

    1. Se a requisição for HTTPS (detectada via $_SERVER['HTTPS'] === 'on', porta 443 ou cabeçalhos de reverse proxy HTTP_X_FORWARDED_PROTO: https), retornar true obrigatoriamente.

    2. Se a configuração do sistema $_GESTOR['development-env'] (instanciada em gestor/config.php a partir de DEVELOPMENT_ENV) for false (padrão de produção), retornar true obrigatoriamente.

    3. Retornar false estritamente se e somente se: a conexão for HTTP pura, não houver HTTPS ativo, e $_GESTOR['development-env'] === true.

  • Substituir as atribuições diretas de 'secure' => true em gestor_sessao_iniciar(), usuario_iniciar_sessao(), gestor.php e módulos correlatos pela chamada a gestor_cookie_is_secure().

2. Comandos CLI de Gestão de Ambiente (c2f env:*)

• Problema Identificado:

  • O framework opera com comportamentos distintos dependendo da variável DEVELOPMENT_ENV (em modo desenvolvimento, componentes, páginas e layouts podem ser lidos diretamente dos arquivos físicos em resources/; em modo produção, a leitura é estrita do banco de dados). Não há comando no CLI para inspecionar ou alternar esse estado durante testes locais.

• Solução Requerida:

  • Implementar no CLI c2f os seguintes comandos e aliases:

  • c2f env:status (ou c2f env:get): Exibe o modo atual (development ou production), detalhando os caminhos ativos e o estado das flags de sanitização e recursos.

  • c2f env:set [development|production] (ou c2f dev:on / c2f dev:off / c2f env:toggle): Altera a variável DEVELOPMENT_ENV no arquivo de ambiente local (.env ou dev-environment/data/environment.json), permitindo alternar rapidamente para validação pré-deploy.

3. Comando CLI de Autenticação Server-Side (c2f auth:cookie)

• Problema Identificado:

  • Para que ferramentas de inspeção, testes ponta a ponta e agentes de IA acessem rotas autenticadas (/gestor/, /admin-paginas/, /chat-intelligence/), é necessário gerar cookies válidos sem depender de submissão de formulários HTML.

• Solução Requerida:

  • Implementar o comando c2f auth:cookie [opções]:

  • Opções: --user=IDENTIFICADOR (padrão admin ou ID 1), --project=ID (opcional), --out=CAMINHO (padrão temp/agent-cookies.txt).

  • Funcionamento: O comando invoca internamente as rotinas criptográficas de usuario_gerar_jwt() e gestor_sessao_iniciar(), assinando a sessão server-side com a chave local.

  • Saída: Grava o arquivo de cookie jar no formato padronizado Netscape (diretamente compatível com curl -b temp/agent-cookies.txt e Playwright) e imprime no terminal a string pronta para cabeçalho HTTP (Cookie: _C2FAUTH_=...; _C2FSID_=...).

4. Comando CLI de Inspeção Headless de Páginas (c2f page:inspect)

• Problema Identificado:

  • Agentes de desenvolvimento não conseguem inspecionar estilos computados (getComputedStyle), animações ativas (getAnimations()) e erros de console JS em tempo de execução sem depender de intervenção humana (pedir screenshots ou cópia de código-fonte).

• Solução Requerida:

  • Implementar o comando c2f page:inspect <url_ou_rota> [opções]:

  • Opções:

    • --project=ID: Identificador do projeto (resolve a URL base local, ex: http://localhost/photon/).

    • --selector="SELETORES_SEPARADOS_POR_VIRGULA": Elementos a serem inspecionados no DOM montado.

    • --computed="PROPRIEDADES_CSS": Lista de propriedades computadas a extrair (ex: animation,display,opacity,visibility).

    • --screenshot[=CAMINHO]: Captura screenshot da página (padrão temp/inspect-screenshot.png).

    • --cookies=CAMINHO: Caminho do arquivo de cookies (padrão temp/agent-cookies.txt se existente).

  • Execução: Dispara uma rotina headless (via Playwright / Chrome headless) que carrega a página com injeção de cookies de sessão, aguarda o ciclo de renderização JS e extrai os dados.

  • Retorno: JSON estruturado no stdout contendo: status (HTTP), url, consoleErrors (array de erros capturados no console), elements (array de seletores com found, computedStyles e activeAnimationsCount), e screenshotPath.

5. Blindagem de Parsing de Flags em Comandos de Projeto (c2f project:*)

• Problema Identificado:

  • Os 8 comandos project:* do CLI (project:sync-resources, project:deploy, project:sync-files, project:sync-db, project:recover, project:update-all, project:update-system, project:sync-core) liam apenas o argumento posicional $input->getArgument(0). Quando o usuário ou agente passava a flag --project=ID, ela era armazenada em $options['project'] e ignorada, acionando o fallback silencioso para o projeto padrão (conn2flow-site).

• Solução Requerida:

  • Atualizar todos os comandos Project*Command.php para resolver o identificador do projeto como: $project = $input->getOption('project') ?? $input->getArgument(0);

  • Validar se o identificador informado existe em environment.json antes da execução, emitindo erro explícito caso contrário.

6. Critérios de Aceitação

1. Sintaxe e Lint: php -l 100% limpo em todos os arquivos alterados e criados.

2. Segurança de Cookies:

   • Em ambiente com DEVELOPMENT_ENV=false ou requisições HTTPS, os cookies são emitidos com Secure: true.

   • Em ambiente com DEVELOPMENT_ENV=true e requisições HTTP locais, os cookies são emitidos com Secure: false.

3. Comandos CLI Funcionais:

   • c2f env:status exibe o status correto da flag DEVELOPMENT_ENV.

   • c2f auth:cookie gera arquivo de cookies válido e utilizável pelo curl.

   • c2f page:inspect retorna JSON estruturado com status, erros de console e propriedades CSS computadas.

   • c2f project:sync-resources --project=ID reconhece a flag --project sem acionar o projeto padrão.

4. Suíte Automatizada: Testes unitários no PHPUnit cobrindo a lógica de gestor_cookie_is_secure() e a execução dos comandos CLI.