prometeu-studio/docs/studio/agendas/Pack Wizard in Assets Workspace Agenda.md

Pack Wizard in Assets Workspace Agenda

Status: Open Domain Owner: docs/studio Cross-Domain Impact: docs/packer

Problem

O workspace Assets já reserva a action area para Pack, mas ainda não existe uma discussão fechada sobre o fluxo exato desse comando no Studio.

O pedido atual não é apenas adicionar um botão. O Pack precisa abrir um modal que funcione como wizard operacional do empacotador e deixe claro:

• o resumo do que será empacotado;
• a validação obrigatória antes do build;
• a regra de bloqueio quando existirem diagnostics em assets incluídos;
• o progresso da geração do artefato;
• e o resumo final do resultado.

Sem essa agenda, há risco de misturar decisão de UX com semântica de packer e de implementar um modal visualmente correto, mas operacionalmente fraco.

Context

O estado atual já sugere várias restrições importantes:

1. o Assets workspace define Pack como ação global de workspace, não como ação do asset selecionado;
2. a spec do Studio já separa Pack do fluxo de staged mutations sensíveis;
3. a spec do packer define assets.pa como artefato runtime autoritativo, com asset_table determinística e baseada apenas nos assets incluídos no build set atual;
4. o packer já trata diagnostics como parte do modelo operacional, então o Studio não deve inventar uma semântica paralela de validação;
5. o usuário precisa de feedback de progresso e de falha com drill-down por asset, não apenas logs.

Artefatos e referências já relevantes:

• docs/studio/specs/4. Assets Workspace Specification.md
• docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md
• docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md
• docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md

Nota de nomenclatura:

• a spec vigente usa assets.pa como nome canônico do artefato;
• esta agenda deve seguir assets.pa, mesmo que a conversa operacional use asset.pa informalmente.

Current Code Context

O contexto atual no código Studio é suficiente para ancorar a discussão:

• o botão Pack foi introduzido na action bar do workspace em prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java;
• o workspace já possui região inline de progresso, painel de logs e integração com eventos do packer;
• ainda não existe wizard de pack nem API explícita de pack em PackerWorkspaceService.

Isso significa que o fluxo precisa ser decidido primeiro e depois propagado para:

• contrato da API do packer;
• eventos operacionais de progresso;
• modelagem de resultado;
• e shell/modal do Studio.

Options

Option A - Single modal with one primary action

Abrir um modal com resumo inicial e um único botão Pack. Ao confirmar, o Studio valida, empacota e mostra sucesso ou falha no mesmo corpo, sem etapas explícitas de wizard.

Option B - Multi-step wizard with explicit operational phases

Abrir um wizard com fases claras:

1. Summary
2. Validation
3. Packing
4. Result

Cada fase deixa explícito o estado operacional atual e evita que o usuário perca contexto entre bloqueio, execução e resultado.

Option C - Split flow with preflight modal plus separate progress dialog

Abrir um modal curto para resumo e validação. Se tudo passar, fechar esse modal e abrir outro diálogo dedicado só ao progresso e resultado do pack.

Tradeoffs

• Option A é mais rápida de implementar, mas colapsa estados diferentes demais em uma única superfície e tende a virar um modal ambíguo.
• Option A também dificulta explicar por que o pack foi bloqueado e o que exatamente falhou por asset.
• Option B exige mais estrutura de estado, mas deixa o fluxo didático, previsível e alinhado ao pedido de wizard empacotador.
• Option B também facilita mapear cada fase para contratos distintos do packer: preflight, validação, execução e resultado.
• Option C separa bem responsabilidades visuais, mas fragmenta a experiência e pode parecer que o usuário saiu de um fluxo para entrar em outro.
• Option C ainda aumenta o custo de coordenação de foco, fechamento e recuperação de erro.

Recommendation

Adotar Option B como baseline.

O Pack deve abrir um wizard modal de workspace, owner do Studio na apresentação e owner do packer na semântica operacional.

Recommended Flow

1. Summary

O wizard abre em um resumo do build atual. Esse resumo deve mostrar pelo menos:

• quantidade de assets registrados e incluídos no build atual;
• quantidade de assets excluídos ou fora do build set;
• indicação de que o output canônico será assets.pa;
• indicação de que a asset_table seguirá a ordem determinística por asset_id, conforme spec;
• artefatos companion previstos quando aplicável.

Regras:

• assets não incluídos no build não entram no pack;
• assets não registrados também não entram no pack;
• o resumo deve deixar explícito que a operação trabalha sobre o build set atual, não sobre todo o workspace.

2. Validation

A segunda fase deve executar uma validação explícita sobre os assets incluídos no build.

Baseline recomendado:

• qualquer diagnostic bloqueante em asset incluído falha a validação e impede o início do pack;
• a tela deve mostrar resumo agregado e amostragem por asset do que falhou;
• a UI deve permitir drill-down por asset sem despejar log cru como explicação principal;
• se houver warnings não bloqueantes, eles podem ser exibidos, mas não devem impedir o Pack.

Modelo didático mínimo da tela:

• topo com contagem de assets validados, aprovados e bloqueados;
• lista por asset com status;
• ao selecionar ou expandir um asset, mostrar diagnostics relevantes daquele asset.

A responsabilidade pela classificação do que bloqueia ou não deve permanecer no packer. O Studio apenas consome e apresenta essa classificação.

3. Packing

Se a validação passar, o wizard entra em fase de execução.

Essa fase deve ser não editável e orientada a progresso.

Regras:

• mostrar barra de progresso com atualização contínua;
• mostrar texto curto da etapa atual;
• manter o usuário no mesmo modal até conclusão, falha ou cancelamento suportado por contrato;
• deixar explícito que o pack está montando assets.pa e a asset_table conforme as specs vigentes;
• logs detalhados podem existir em área secundária, mas não substituem o indicador principal de progresso.

Semântica recomendada:

• o packer expõe eventos ou snapshots de progresso por operação;
• o Studio mapeia isso para uma barra de progresso e rótulos humanos;
• o wizard não deve inferir progresso a partir de timers artificiais.

4. Result

Ao concluir, o wizard deve mostrar um resumo final do resultado.

O resumo deve cobrir:

• status final: sucesso parcial ou falha;
• quantidade de assets efetivamente empacotados;
• artefatos emitidos;
• duração da operação;
• falhas ou avisos finais, quando existirem.

Se houver falha depois de a validação ter passado, a tela final deve diferenciar:

• falha de validação;
• falha de execução/geração;
• e falha de persistência/emissão.

Contract Direction

Para a próxima onda de decisão, o contrato recomendado é separar pelo menos três responsabilidades no packer:

1. preflight summary do build set atual;
2. validation do build set com bloqueios agregados por asset;
3. pack execution com progresso estruturado e resultado final.

O Studio deve orquestrar essas fases no wizard, mas não redefinir:

• quais assets entram no build set;
• o que conta como diagnostic bloqueante;
• a ordem da asset_table;
• ou o que exatamente compõe assets.pa.

UI Direction

O wizard deve ser operacional, não um formulário tradicional.

Direção recomendada:

• stepper simples no topo ou lateral;
• corpo central com conteúdo da fase;
• ações de navegação controladas pelo estado operacional;
• Next bloqueado quando a validação falhar;
• Pack disponível apenas quando a fase de validação estiver limpa;
• Close ou Done só ao final, ou em estados seguros de abortar.

Open Questions

1. O packer deve expor summary, validate e pack como chamadas separadas ou uma única operação com fases internas observáveis?
2. O pack bloqueia apenas por diagnostics blocking ou também por certos warnings elevados a gate de build?
3. A amostragem por asset na fase de validação deve mostrar todos os diagnostics do asset ou apenas os bloqueantes por padrão?
4. O wizard deve permitir exportar ou copiar o resumo de falhas para facilitar correção fora do modal?
5. Existe cancelamento real suportado pelo packer durante a fase Packing, ou o primeiro wave deve tratar a operação como não cancelável?
6. O resultado final deve listar também os companion artifacts ou isso fica para drill-down secundário?
7. O build set do Pack neste fluxo é estritamente registered + included, ou existe necessidade futura de variantes de pack profile?

Suggested Next Step

O próximo passo correto é converter esta agenda em uma decision owner de docs/studio, com propagação explícita para docs/packer.

Essa decision deve fechar:

1. o shape do wizard e suas fases;
2. o gate de validação baseado em diagnostics dos assets incluídos;
3. o contrato mínimo de API/eventos que o packer precisa expor para suportar o wizard;
4. a distinção entre falha de validação e falha de execução;
5. o vocabulário canônico do resultado final em torno de assets.pa e asset_table.

Depois disso, o trabalho deve ser decomposto em pelo menos dois planos:

1. um PR/plan em docs/packer para summary, validation, pack execution, progress e result contract;
2. um PR/plan em docs/studio para shell do wizard, fases, binding de progresso e tela de resultado.