Scenario Generator

Crie planos de execucao (scenarios) a partir de pedidos em linguagem natural. Gere o plan.json e os arquivos de apoio (behaviors, curl, SQL mock) seguindo o padrao do repositorio.

Entrada minima a confirmar

• •Nome da feature, ticket e ambiente (metadata).
• •Quais evidencias sao esperadas (browser, api, sql, cli, specialist, logstream).
• •Dependencias externas (endpoints, arquivos, credenciais) e se devem ser mockadas.
• •Ordem do fluxo e regras de export/require entre steps.

Se faltar informacao critica, faca 1-2 perguntas objetivas e siga.

Onde pesquisar primeiro

Leia references/paths.md para a lista de arquivos do repo e padroes de busca.

1. •Reaproveitar padroes existentes:
   • •scenarios/ e examples/ para planos similares
   • •docs/howto/steps.md e docs/howto/create-plans.md para formato
   • •docs/howto/browser-behaviors.md para actions Playwright
   • •docs/howto/inputs-context.md para exports/requires
2. •Usar rg --files para localizar plan.json, behaviors.json, .curl, .sql, .csv.

Fluxo de trabalho recomendado

1. •Resumir o pedido do usuario em steps declarativos.
2. •Mapear cada step para o dominio correto:
   • •browser, api, sqlEvidence, cli, specialist, logstream
3. •Definir estrutura de pasta:
   • •scenarios/<slug>/plan.json
   • •scenarios/<slug>/behaviors.json (se houver browser)
   • •scenarios/<slug>/requests/*.curl (se houver api)
   • •scenarios/<slug>/sql/*.sql e scenarios/<slug>/sql/*.csv (se houver sqlEvidence)
4. •Escrever plan.json com metadata, steps e referencias de arquivos.
5. •Aplicar exports/requires para encadear dados.
6. •Validar rapidamente com npm start -- --plan <path> --out runs.

Modelo base de plan.json

{
  "metadata": { "feature": "minha-feature", "ticket": "ABC-123", "env": "local" },
  "behaviorsPath": "behaviors.json",
  "curlPath": "requests/requests.curl",
  "steps": [
    { "id": "login", "type": "browser", "behaviorId": "login" },
    {
      "id": "get-itens",
      "type": "api",
      "exports": {
        "itemId": { "source": "responseData", "jsonPath": "items[0].id" }
      }
    },
    {
      "id": "sql-count",
      "type": "sqlEvidence",
      "config": {
        "sql": {
          "queryPath": "sql/count.sql",
          "resultPath": "sql/count.csv",
          "expectRows": 1
        }
      }
    }
  ]
}

Behaviors (browser)

• •Sempre nomear behaviorId conforme o objetivo do step.
• •Preferir actions declarativas (click, fill, waitForResponse, waitForRequest).
• •Evitar waits arbitrarios; usar waitForRequest/waitForResponse quando houver eventos de API.

Exemplo de trecho:

{
  "behaviors": {
    "login": {
      "actions": [
        { "type": "goto", "url": "https://app.exemplo.com" },
        { "type": "fill", "selector": "#email", "text": "{{userEmail}}" },
        { "type": "click", "selector": "button[type=submit]" },
        { "type": "waitForResponse", "url": "/api/session", "status": 200 }
      ]
    }
  }
}

Variaveis e env

• •Use sempre {{chave}} (mustache) para interpolar contexto.
• •Se precisar de env, inclua inputs.envPrefix e mencione .env.
• •Exemplo .env: AUTO_TOKEN=abc vira {{TOKEN}} no contexto.

Erros e validacoes

• •SQL pode falhar com expectRows ou query invalida.
• •CLI falha com exitCode e errorPatterns.
• •API so falha em erros de rede/timeout; se precisar falhar em 4xx/5xx, deixe isso explicito no plan (ex: validar com exports + requires).

SQL evidence

• •Use arquivos mock por padrao: query.sql e result.csv.
• •Configure expectRows quando o resultado precisa validar quantidade.

Curl (API)

• •Centralize chamadas em .curl e use curlPath no plan.
• •Use placeholders {{variavel}} no curl e exports no step api.

Checklist de entrega

• •plan.json com steps em ordem e metadata completa.
• •Arquivos auxiliares criados e referenciados corretamente.
• •exports e requires coerentes.
• •npm start -- --plan <path> --out runs executa sem erro de schema.

Regras e limites

• •Nao adicionar credenciais reais no repo.
• •Preferir mocks para SQL e API quando nao houver ambiente real.
• •Manter comentarios minimos e arquivos em ASCII.