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.

Boundary baseline desta agenda:

• o Studio é casca operacional;
• o Studio chama serviços do packer, observa progresso e apresenta estado;
• o trabalho bruto de summary, validation, packing e result pertence ao packer;
• o Studio não deve reimplementar regras de build, gating ou ordenação.

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.

Leitura operacional explícita:

• o wizard é Studio-owned apenas como shell de interação;
• a semântica do pack é packer-owned ponta a ponta.

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. O Studio é owner apenas da apresentação e navegação do modal. O packer é owner da semântica operacional, da validação, da execução e do resultado.

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.
• o Studio apenas apresenta esse resumo; ele não recompõe localmente o build set.

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 validação deve ser tratada como processo packer-owned semelhante a um deep sync dry-run, mas restrito ao conjunto registered + included in build;
• 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.

Baseline fechado nesta agenda wave:

• a fase de validação mostra diagnostics bloqueantes por padrão;
• a tela deve permitir que o developer inspecione contexto adicional quando necessário;
• esse drill-down adicional não muda o foco principal da fase, que é explicar o gate de bloqueio.

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

Direção mais precisa para esta agenda:

• a validação não é uma checagem local do Studio;
• a validação é uma operação explícita do packer;
• ela reutiliza a lógica de reconciliação/inspeção profunda necessária para afirmar se o build set atual pode ser empacotado;
• mas seu escopo é apenas o conjunto de assets que realmente participariam do pack.

3. Packing

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

Essa fase deve ser não editável, operante 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.
• durante Packing, o wizard não deve expor affordances de edição ou revisão que façam a operação parecer reversível ou parcialmente configurável.

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.

Baseline fechado para a primeira versão:

• não há cancelamento durante Packing;
• o modal permanece em estado operante até conclusão ou falha;
• a UI não deve simular cancelamento sem suporte cooperativo real do packer.

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.

Baseline fechado nesta agenda wave:

• o resumo principal prioriza assets.pa, duração e total de assets empacotados;
• companion artifacts ficam em drill-down secundário;
• os diagnostics do resultado tendem a já existir nos assets e não precisam dominar a superfície principal.

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 como dry-run packer-owned semelhante a deep sync, com bloqueios agregados por asset;
3. pack execution com progresso estruturado e resultado final.

Baseline fechado nesta agenda wave:

• summary, validation e pack execution são chamadas distintas;
• o Studio não deve iniciar pack execution para conseguir summary ou validation;
• a separação deve permanecer visível na API consumida pelo Studio.

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.

Em termos práticos:

• o Studio chama;
• o packer decide;
• o Studio mostra.

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.

Resolved In This Agenda Wave

Os seguintes pontos ficam fechados como baseline para a próxima decision:

1. summary, validation e pack execution são chamadas distintas.
2. A validação mostra diagnostics bloqueantes por padrão e permite inspeção adicional para o developer.
3. A primeira versão não suporta cancelamento durante Packing.
4. Companion artifacts ficam em drill-down secundário no resultado final.
5. A primeira versão não exporta nem copia o resumo de falhas.
6. Pode existir um botão dumb na UI como lembrete explícito de feature futura, sem comportamento operacional no v1.

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.