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.