prometeu-studio/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0009	studio-debugger-workspace-integration	Integrar ../debugger ao Studio como workspace dedicado	open	2026-03-30			studio debugger workspace integration shell

Pain

O shell do Studio ja anuncia WorkspaceId.DEBUG e exibe Debug na workspace rail, mas nao registra nenhum workspace concreto para esse slot.

Hoje isso deixa o produto num estado inconsistente:

• a shell promete um Debugger/Profiler como workspace baseline;
• MainView publica a opcao Debug na navegacao;
• WorkspaceHost exige que o workspace esteja registrado;
• a implementacao real do Debug continua fora do Studio, no sibling repo ../debugger.

Sem uma discussion canonica, a integracao tende a cair em um de tres atalhos ruins:

• abrir o debugger como app externo e fingir que isso equivale a um workspace;
• embutir a aplicacao JavaFX existente dentro do Studio sem alinhar ciclo de vida, eventos e theming;
• reescrever tudo no Studio e perder o que o ../debugger ja estabilizou em protocolo, controle de execucao e estado.

Context

Domain owner: studio Owner surface: docs/specs/studio Cross-domain input: sibling repo ../debugger

Superficies relevantes hoje:

• docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md ja define Debugger/Profiler como parte do baseline workspace set;
• docs/specs/studio/2. Studio UI Foundations Specification.md exige um modelo de workspaces orientado a eventos, com bus por workspace e republishing para o bus global;
• prometeu-studio/src/main/java/p/studio/window/MainView.java ja inclui WorkspaceId.DEBUG na rail, mas o register(...) correspondente esta comentado;
• prometeu-studio/src/main/java/p/studio/workspaces/Workspace.java exige um contrato de rootNode(), load(), unLoad() e integra o workspace a um StudioWorkspaceEventBus;
• ../debugger ja existe como aplicacao JavaFX separada, com Application/Stage, FXML, Dagger, i18n, cliente DevTools, protocolo TCP/JSONL e controle de execucao.

O boundary de produto tambem ja aponta a direcao correta:

• o shell do Studio deve enquadrar workspaces sem absorver detalhe operacional;
• logs e detalhe de execucao pertencem ao workspace que os possui;
• o debugger e uma superficie de execucao, nao um detalhe lateral do painel global de utilidades.

Open Questions

• O objetivo da primeira integracao e hospedar a experiencia atual do ../debugger quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio?
• Quais partes do ../debugger sao core reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira?
• Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo?
• Quem passa a ser o owner do ciclo de vida da sessao de debug: o DebugWorkspace, a shell do Studio, ou um servico compartilhado com a run surface?
• Como eventos, telemetria, logs e estados do debugger entram no bus de workspace e no bus global sem criar um segundo sistema paralelo de notificacao?
• O primeiro corte deve incluir profiler junto com debugger, ou o baseline inicial fecha apenas debugger e deixa profiling como extensao posterior?
• Como preservar tema, i18n e consistencia visual se parte da UI atual do ../debugger ainda estiver em FXML e recursos proprios?
• O app standalone ../debugger continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario?

Options

Option A - Launcher externo a partir do Studio

• Approach: O Studio oferece um ponto de entrada para abrir ../debugger como processo/janela externa, mantendo a integracao dentro da shell apenas como acao de lancamento.
• Pro: Menor custo inicial e reaproveitamento maximo da app atual.
• Con: Nao entrega um workspace real do Studio, fragmenta estado/sessao e conflita com a baseline shell spec.
• Maintainability: Fraca como arquitetura final. Pode servir no maximo como ponte temporaria, mas nao resolve o contrato de workspace.

Option B - Embutir a UI atual do debugger quase inteira dentro de um workspace host

• Approach: Reaproveitar FXML/controllers do ../debugger e monta-los dentro de um DebugWorkspace, fazendo adaptacoes localizadas de DI, lifecycle e navegacao.
• Pro: Reaproveita mais UI existente e acelera a primeira tela funcional.
• Con: Carrega para dentro do Studio um bootstrap orientado a Application/Stage, com modelo proprio de lifecycle, theming e eventos que nao casa naturalmente com o contrato de workspace atual.
• Maintainability: Media para baixa. Economiza reescrita imediata, mas cristaliza um boundary torto entre app standalone e workspace embutido.

Option C - Workspace nativo do Studio apoiado em core extraido do debugger

• Approach: Tratar o ../debugger como fonte de servicos, protocolo, estado e controle de execucao reaproveitaveis, mas implementar o DebugWorkspace como composicao nativa do Studio sobre o contrato Workspace + bus tipado + lifecycle-managed controls.
• Pro: Alinha shell spec, workspace framework e boundary de produto, sem descartar o investimento ja feito no debugger.
• Con: Exige separar explicitamente o que e core reutilizavel e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico.
• Maintainability: Forte. Preserva a direcao arquitetural correta e permite que Studio e app standalone compartilhem nucleo sem colapsarem num acoplamento acidental.

Option D - Migracao integral do debugger para dentro do Studio

• Approach: Absorver codigo e UI do ../debugger para dentro dos modulos do Studio e tratar a aplicacao standalone como legado a ser aposentado.
• Pro: Simplifica ownership futuro se o produto decidir convergir totalmente para uma unica shell.
• Con: E a aposta mais cara e mais irreversivel, antes mesmo de fechar o contrato de integracao e o que ainda deve continuar independente.
• Maintainability: Media. Pode ser boa no longo prazo, mas e prematura enquanto o boundary entre workspace e app standalone ainda nao esta fechado.

Discussion

O ponto principal nao e "como mostrar alguma tela de debug no Studio". O ponto principal e decidir qual contrato queremos estabilizar entre:

• a shell do Studio, que ja assume workspaces independentes e orientados a eventos;
• o DebugWorkspace, que precisa ser um workspace real, com ownership claro de detalhe operacional;
• e o ../debugger, que hoje concentra bootstrap de app, protocolo, estado e UI numa aplicacao separada.

O fato de a rail ja ter Debug e a spec ja falar em Debugger/Profiler indica que a integracao nao e trabalho especulativo. Ela ja faz parte da topologia esperada do Studio.

Por isso, as opcoes que preservam o debugger apenas como janela externa ou que arrastam a app inteira para dentro do host sem remodelar o boundary resolvem pouco:

• a primeira evita o trabalho agora, mas nao entrega o produto prometido pela shell;
• a segunda reaproveita UI, mas importa um modelo arquitetural que nao conversa bem com Workspace, StudioWorkspaceEventBus, theming compartilhado e lifecycle-managed controls.

O caminho mais coerente parece ser separar o problema em duas camadas:

1. um debugger core reaproveitavel, com sessao, protocolo, telemetria, logs e controle de execucao;
2. uma composicao de DebugWorkspace nativa do Studio, que consome esse core como mais um workspace do shell.

Isso nao obriga uma reescrita total imediata da logica do debugger. Obriga apenas que a UI e o bootstrap standalone parem de ser tratados como se fossem a fronteira certa de integracao.

Resolution

Recommended direction: seguir com Option C.

A agenda deve convergir para uma decisao com os seguintes fechamentos:

1. Debug no Studio deve virar um workspace real, nao apenas launcher de app externo;
2. o boundary correto de reaproveitamento esta em servicos/protocolo/estado do debugger, nao no bootstrap Application/Stage como unidade de integracao;
3. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n;
4. o destino do app standalone precisa ser explicitado: consumidor paralelo do mesmo core durante migracao, ou superficie secundaria apos a integracao;
5. o primeiro corte deve declarar se profiler entra junto com debugger ou fica explicitamente fatiado para depois.

Next step suggestion: converter esta agenda em uma decision que feche o modelo de integracao, o boundary de ownership entre studio e ../debugger, a topologia de dependencias entre repositorios e o escopo da primeira wave de DebugWorkspace.