rudrankriyam/asc-workflow

O que asc-workflow faz?

Defina, valide, execute, retome e audite automações de múltiplas etapas locais ao repositório com o comando asc workflow e o arquivo .asc/workflow.json, incluindo saídas de etapas e fluxos seguros de release/TestFlight.

Visão Geral

Este skill permite que agentes de IA e desenvolvedores criem e gerenciem workflows de automação diretamente dentro do repositório, mantendo o controle de versão e a rastreabilidade. Os workflows são definidos no arquivo .asc/workflow.json e podem ser executados, pausados, retomados e auditados através do comando asc workflow.

Estrutura do Workflow

Cada workflow é composto por uma série de etapas, onde cada etapa pode executar comandos, scripts ou ações específicas. É possível definir saídas de etapas que podem ser passadas para etapas subsequentes, permitindo fluxos de trabalho dinâmicos e encadeados.

Exemplo de arquivo .asc/workflow.json

{
  "workflows": [
    {
      "name": "release-appstore",
      "description": "Fluxo seguro de release para App Store Connect",
      "steps": [
        {
          "id": "build",
          "command": "xcodebuild -project MeuApp.xcodeproj -scheme Release archive",
          "outputs": {
            "archivePath": "~/Library/Developer/Xcode/Archives/MeuApp.xcarchive"
          }
        },
        {
          "id": "upload",
          "command": "xcrun altool --upload-app -f {{outputs.build.archivePath}} -u {{env.APPLE_ID}} -p {{env.APP_SPECIFIC_PASSWORD}}"
        }
      ]
    }
  ]
}

Comandos

Comando	Descrição
asc workflow run <workflow-name>	Executa um workflow definido no arquivo .asc/workflow.json.
asc workflow resume <workflow-name>	Retoma um workflow que foi pausado ou interrompido anteriormente.
asc workflow audit <workflow-name>	Exibe o histórico e status de execuções anteriores do workflow.
asc workflow validate <workflow-name>	Valida a sintaxe e as dependências do workflow sem executá-lo.

Saídas de Etapas

As saídas de etapas permitem que informações geradas em um passo sejam utilizadas em passos seguintes. Elas são definidas no campo outputs de cada etapa e referenciadas por meio da sintaxe {{outputs.stepId.key}}.

Fluxos Seguros de Release/TestFlight

Este skill suporta a criação de workflows seguros para liberação de builds para a App Store Connect e para o TestFlight, garantindo que apenas ações validadas e autorizadas sejam executadas. É altamente recomendável utilizar variáveis de ambiente para credenciais sensíveis, como IDs da Apple e senhas específicas de aplicativo.

Auditoria e Retomada

• Auditoria: O comando audit fornece um log detalhado de todas as execuções, incluindo sucessos, falhas e saídas intermediárias.
• Retomada: Se um workflow falhar ou for interrompido, é possível retomá-lo a partir da última etapa bem-sucedida sem perder o progresso.

Requisitos

• Node.js >= 16
• CLI asc instalada globalmente
• Arquivo .asc/workflow.json no diretório raiz do repositório

Exemplo Completo

Veja abaixo um workflow completo para build e envio ao TestFlight:

{
  "workflows": [
    {
      "name": "testflight-release",
      "description": "Build e upload para TestFlight",
      "steps": [
        {
          "id": "clean",
          "command": "xcodebuild clean -workspace MeuApp.xcworkspace -scheme Release"
        },
        {
          "id": "archive",
          "command": "xcodebuild archive -workspace MeuApp.xcworkspace -scheme Release -archivePath /tmp/MeuApp.xcarchive"
        },
        {
          "id": "export",
          "command": "xcodebuild -exportArchive -archivePath /tmp/MeuApp.xcarchive -exportPath /tmp/MeuApp.ipa -exportOptionsPlist exportOptions.plist",
          "outputs": {
            "ipaPath": "/tmp/MeuApp.ipa"
          }
        },
        {
          "id": "upload-testflight",
          "command": "xcrun altool --upload-app -f {{outputs.export.ipaPath}} -u {{env.APPLE_ID}} -p {{env.APP_SPECIFIC_PASSWORD}} --type ios"
        }
      ]
    }
  ]
}

Resolução de Problemas

• Erro de validação: Execute asc workflow validate para verificar se a estrutura JSON está correta.
• Falha em etapa: Use asc workflow audit para inspecionar logs e identificar a causa.
• Credenciais inválidas: Verifique se as variáveis de ambiente necessárias estão definidas.

Contribuindo

Sinta-se à vontade para abrir issues ou pull requests no repositório oficial: github.com/rudrankriyam/asc-workflow.