From 0f056a1ea14aa4830dbdde51a10b4cb6aa91e711 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 31 Mar 2026 08:00:10 +0100 Subject: [PATCH] prometeu-vsf --- discussion/index.ndjson | 3 +- ...012-studio-editor-document-vfs-boundary.md | 200 ++++++++++++++++++ ...-prometeu-vfs-project-document-boundary.md | 178 ++++++++++++++++ ...15-propagate-dec-0009-into-studio-specs.md | 156 ++++++++++++++ ...ild-prometeu-vfs-filesystem-backed-core.md | 185 ++++++++++++++++ ...ject-session-ownership-for-prometeu-vfs.md | 153 ++++++++++++++ ...018-migrate-code-editor-to-prometeu-vfs.md | 168 +++++++++++++++ .../fragments/.studio/activities.json | 10 + 8 files changed, 1052 insertions(+), 1 deletion(-) create mode 100644 discussion/workflow/agendas/AGD-0012-studio-editor-document-vfs-boundary.md create mode 100644 discussion/workflow/decisions/DEC-0009-studio-prometeu-vfs-project-document-boundary.md create mode 100644 discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md create mode 100644 discussion/workflow/plans/PLN-0016-build-prometeu-vfs-filesystem-backed-core.md create mode 100644 discussion/workflow/plans/PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md create mode 100644 discussion/workflow/plans/PLN-0018-migrate-code-editor-to-prometeu-vfs.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 8952b49a..bc5ef319 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":12,"AGD":12,"DEC":9,"PLN":15,"LSN":27,"CLSN":1}} +{"type":"meta","next_id":{"DSC":13,"AGD":13,"DEC":10,"PLN":19,"LSN":27,"CLSN":1}} {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} @@ -10,3 +10,4 @@ {"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]} {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} +{"type":"discussion","id":"DSC-0012","status":"open","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[{"id":"AGD-0012","file":"AGD-0012-studio-editor-document-vfs-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0009","file":"DEC-0009-studio-prometeu-vfs-project-document-boundary.md","status":"in_progress","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0012"}],"plans":[{"id":"PLN-0015","file":"PLN-0015-propagate-dec-0009-into-studio-specs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0016","file":"PLN-0016-build-prometeu-vfs-filesystem-backed-core.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0017","file":"PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]},{"id":"PLN-0018","file":"PLN-0018-migrate-code-editor-to-prometeu-vfs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0009"]}],"lessons":[]} diff --git a/discussion/workflow/agendas/AGD-0012-studio-editor-document-vfs-boundary.md b/discussion/workflow/agendas/AGD-0012-studio-editor-document-vfs-boundary.md new file mode 100644 index 00000000..63c287c0 --- /dev/null +++ b/discussion/workflow/agendas/AGD-0012-studio-editor-document-vfs-boundary.md @@ -0,0 +1,200 @@ +--- +id: AGD-0012 +ticket: studio-editor-document-vfs-boundary +title: Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio +status: in_progress +created: 2026-03-31 +resolved: 2026-03-31 +decision: DEC-0009 +tags: + - studio + - editor + - workspace + - vfs + - filesystem + - boundary +--- + +## Pain + +O `Code Editor` do Studio ja fechou a primeira wave como shell editorial read-only, mas a composicao concreta ainda instancia diretamente os servicos que leem arvore e conteudo do filesystem. + +Isso deixa uma ambiguidade arquitetural: + +- o shell do workspace deveria coordenar layout, sessao e sincronizacao; +- mas hoje ele ainda conhece diretamente os adaptadores de leitura estrutural e de leitura de documento; +- e nao esta explicito se a proxima evolucao deve continuar como `filesystem services` locais ou subir para um boundary mais claro de `document/tree VFS`. + +Sem fechar esse ponto agora, o editor corre risco de crescer com responsabilidades misturadas: + +- tree snapshot; +- open-file buffers; +- refresh/watchers; +- overlays de documento em memoria; +- e futuras fontes nao estritamente filesystem-backed. + +## Context + +Domain owner: `studio` +Owner surface: `docs/specs/studio` + +Superficies relevantes: + +- `docs/specs/studio/5. Code Editor Workspace Specification.md` ja exige separacao entre structural snapshot e opened-file content, mantendo o filesystem como source of truth nesta wave; +- `discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md` consolida que o Studio possui o shell editorial, nao um IDE semantico completo; +- `EditorWorkspace` ainda instancia diretamente `EditorProjectSnapshotService` e `EditorFileBufferLoader`; +- `EditorProjectSnapshotService` e `EditorFileBufferLoader` usam `Files.*` diretamente como backend concreto. +- o workspace Gradle ja reserva `prometeu-lsp:prometeu-lsp-api` e `prometeu-lsp:prometeu-lsp-v1`, mas hoje esses modulos ainda nao tem codigo; +- os roadmaps de LSP tratam `prometeu-lsp` como superficie futura para handlers/endpoints semanticos e itens como `didChangeWatchedFiles`. + +Clarificacao importante para esta discussion: + +- quando falamos em `VFS` aqui, nao estamos propondo um filesystem universal do produto; +- o packer continua com ownership proprio de runtime/workspace/asset semantics; +- as entidades nao se veem por padrao; +- o recorte aqui e um boundary do `Code Editor` para `tree`, `view` e `open files`, inclusive conteudo em memoria. + +## Open Questions + +- [x] Nesta etapa, o boundary transporta apenas o que o `workspace editor` ja tem hoje; nada novo entra no escopo funcional. +- [x] O `prometeu-vfs` nao deve expor apenas RPC; ele tambem deve receber e emitir um subconjunto selecionado de eventos como parte explicita da propria API. +- [x] O `Project Navigator` consome uma entidade que representa a arvore inteira, sem acessar filesystem diretamente, mas deve poder requerer atualizacoes mais pontuais do que um reload completo. +- [x] A `tree` do `prometeu-vfs` deve ser estrutural e de dados apenas, nao uma tree visual nem um view model de UI. +- [x] O `open files` passa a abrir a partir do `prometeu-vfs`, inclusive quando o backend concreto continuar sendo o disco. +- [x] Regras de arquivos, plugins e de suporte ou nao suporte pertencem ao `prometeu-vfs`; o Studio apenas apresenta o erro/estado ao usuario. +- [x] Nesta primeira wave, eventos publicos ficam de fora; tudo permanece interno ate existir necessidade clara de exposicao contratual. +- [x] `Watchers` ficam fora desta primeira decisao; `refresh` permanece somente manual. +- [x] O boundary nasce como primitive util para o dominio `studio`; hoje o editor consome, e futuramente o `prometeu-lsp` podera consumir tambem. +- [x] O `document/tree manager` vive na sessao de projeto do Studio, e o snapshot do `prometeu-vfs` cobre apenas conteudo do projeto. +- [x] Criar um novo `prometeu-vfs` e manter `prometeu-lsp` reservado para a camada futura de protocolo/handlers parece melhor do que renomear o namespace atual. + +## Options + +### Option A - Manter servicos filesystem locais no editor +- **Approach:** Continuar com `EditorProjectSnapshotService` e `EditorFileBufferLoader` como helpers concretos do workspace, extraindo apenas pequenos refinamentos locais. +- **Pro:** Menor custo imediato e menos abstracao. +- **Con:** O shell continua acoplado ao backend concreto e a evolucao para overlays, watchers ou backends alternativos fica difusa. +- **Maintainability:** Media para baixa. Funciona enquanto o editor permanecer estritamente read-only e filesystem-first. + +### Option B - Extrair portas pequenas separadas, sem chamar isso de VFS +- **Approach:** Definir interfaces independentes para `project tree snapshot` e `document content loading`, ambas filesystem-backed por baixo. +- **Pro:** Resolve o acoplamento principal com mudanca pequena e preserva clareza. +- **Con:** Pode virar um VFS fatiado informalmente, sem um modelo claro quando overlays de memoria entrarem. +- **Maintainability:** Media. Boa transicao curta, mas com risco de proliferar portas parciais. + +### Option C - Definir um VFS documental estreito para o Code Editor +- **Approach:** Criar um boundary explicito do editor que seja owner de arvore virtual do projeto e documentos abertos/em memoria, com backend inicial filesystem-backed e overlays de sessao como extensao prevista. +- **Pro:** Fecha a fronteira certa: o workspace consome um modelo de documentos/arvore e deixa de conhecer `Files.*` ou loaders concretos. +- **Con:** Exige nomear melhor contratos, identidade de documento, estrategia de refresh e como snapshot estrutural convive com buffers abertos. +- **Maintainability:** Forte. Preserva a intencao de shell editorial e abre caminho limpo para write wave, overlays e fontes alternativas sem acoplar isso ao packer. + +### Option D - Criar um novo modulo `prometeu-vfs` com lifecycle de projeto no Studio +- **Approach:** Criar um modulo-base de VFS/document manager (`prometeu-vfs`) que o Studio instancia por projeto, fora do foco do workspace, com watchers/refresh/overlays encapsulados ali; o editor vira consumidor desse servico, enquanto `prometeu-lsp` permanece reservado para a futura camada de protocolo/handlers. O modulo deve expor uma API mista de chamadas RPC e um subconjunto disciplinado de eventos publicos. +- **Pro:** Alinha melhor a ownership real do estado documental, porque ele continua vivo mesmo sem o `Code Editor` estar ativo; tambem prepara o caminho para um futuro `prometeu-lsp` consumir o mesmo substrate em vez de reinventar sincronizacao. +- **Con:** Obriga a decidir desde ja a topologia entre `studio`, `vfs` e um futuro `lsp`, alem de exigir definicao disciplinada da fronteira entre eventos publicos e eventos internos para nao vazar detalhes internos como API acidental. +- **Maintainability:** Forte, desde que o scope continue estrito a documentos/arvore de projeto e nao derive para um filesystem universal do produto. + +### Option E - Criar um VFS generico de Studio desde ja +- **Approach:** Elevar o boundary para uma primitive ampla do Studio, candidata a servir editor, assets, debugger e outras workspaces. +- **Pro:** Promete reutilizacao ampla. +- **Con:** Generaliza antes de existir evidencia suficiente de consumo compartilhado e arrisca misturar dominios que hoje precisam continuar separados. +- **Maintainability:** Baixa neste momento. A abstracao tende a nascer grande demais e cedo demais. + +## Discussion + +O ponto principal nao e substituir o disco por uma simulacao abstrata. +O ponto principal e impedir que o `Code Editor` continue dono acidental de concerns que deveriam morar em um boundary proprio de documentos e arvore. + +O estado normativo atual ja separa corretamente: + +1. snapshot estrutural do projeto para navegacao; +2. buffers de documentos abertos para sessao; +3. filesystem como source of truth na primeira wave. + +O que falta e transformar essa separacao conceitual em uma fronteira arquitetural explicita. + +Se o boundary nascer estreito, ele pode continuar filesystem-backed sem conflito: + +- o navigator pede uma arvore/snapshot; +- o open-files pede documentos; +- overlays de memoria podem passar a viver no mesmo boundary quando write/draft semantics entrarem; +- e o workspace continua coordenando UX, nao I/O. + +O novo ponto trazido nesta discussion refinou ainda mais o boundary correto: + +- o estado documental do projeto pode precisar continuar vivo mesmo quando o `Code Editor` nao estiver no foco; +- refresh manual e reconciliacao de documento sao concerns de runtime do boundary, nao do layout do workspace; +- portanto, o owner mais coerente deixa de ser o `EditorWorkspace` e passa a ser um servico de projeto do Studio que o editor consome. + +Outro fechamento importante e que esse servico nao deve ser pensado como biblioteca puramente sincrona de funcoes: + +- o `prometeu-vfs` deve oferecer chamadas de API para comandos/queries diretas; +- o modulo pode manter eventos internos como parte do seu runtime; +- mas nesta primeira wave nenhum evento precisa sair como API publica; +- isso preserva flexibilidade interna enquanto o boundary estrutural e documental ainda esta sendo estabilizado. + +Nesse modelo, a pilha correta tende a ser: + +1. `Studio project session` instancia o manager documental; +2. `prometeu-vfs` ou equivalente implementa tree/document/watchers/overlays; +3. `EditorWorkspace` observa e consome esse estado; +4. um futuro `prometeu-lsp` pode consumir o mesmo substrate acima dele, e nao o contrario. + +Um fechamento importante desta agenda e que a palavra `tree` em `prometeu-vfs` significa estrutura de dados do projeto, nao componente visual: + +- o `prometeu-vfs` deve publicar nos estruturais, paths, parent/children, tipos de entrada, identidades e metadados documentais necessarios; +- o `prometeu-vfs` nao deve carregar concerns de UI como expansao visual, selecao, foco, scroll, reveal, icones ou chrome de navigator; +- o `Project Navigator` do Studio continua owner do tree visual e de qualquer view model derivado para apresentacao; +- tags ou metadados produzidos pelo `prometeu-vfs` podem informar a UI, mas a decisao de como renderizar continua no Studio. + +O mesmo vale para o modelo de comunicacao: + +- RPC cobre comandos/queries como abrir documento, pedir snapshot, reconciliar, listar documentos ou obter conteudo atual; +- eventos internos podem cobrir transicoes observaveis do runtime como snapshot atualizado, documento mutado, divergencia detectada ou refresh concluido; +- esses eventos permanecem encapsulados nesta wave; +- a API oficial inicial fica concentrada em RPC/comandos/queries, sem publication obrigatoria para fora do modulo. + +O fato de `prometeu-lsp` ainda estar vazio torna qualquer mudanca barata em codigo, mas a decisao mais limpa continua sendo criar `prometeu-vfs` como modulo novo: + +- o nome `prometeu-lsp` ja esta referenciado nos roadmaps como superficie futura de protocolo/handlers; +- renomear agora e barato em codigo, mas continua sendo ruidoso editorialmente; +- criar `prometeu-vfs` preserva a hierarquia conceitual certa: `vfs` como substrate, `lsp` como consumidor futuro. + +Isso e diferente de um `VFS universal`: + +- nao absorve regras do packer; +- nao redefine ownership de assets; +- nao cria dependencia cruzada entre domínios; +- e nao exige que todas as workspaces do Studio passem a usar o mesmo modelo desde o dia 1. + +O nome `VFS` so vale a pena se o contrato realmente virar owner de: + +- identificacao de documentos, +- leitura estrutural, +- conteudo resolvido para open files, +- e futura sobreposicao de estado em memoria. + +Se a equipe quiser evitar peso terminologico agora, `Option B` e um passo valido. +Mas a direcao arquitetural mais coerente parece ser nomear logo o boundary correto e mantê-lo deliberadamente estreito. + +## Resolution + +Recommended direction: seguir com **Option D**, com o escopo estrito de `Option C` e o corte funcional limitado ao que o `EditorWorkspace` ja faz hoje. + +Fechamento recomendado para a proxima `decision`: + +1. o `Code Editor` deve consumir um boundary proprio de `tree + document content`, em vez de instanciar loaders filesystem concretos; +2. nesta etapa, o boundary deve transportar apenas as capacidades que o `EditorWorkspace` ja possui hoje, sem adicionar novas features editoriais; +3. esse boundary deve viver como servico de sessao de projeto do Studio, nao como detalhe de lifecycle do `EditorWorkspace`; +4. esse boundary comeca como `filesystem-backed`, e o Studio passa a tocar o disco atraves do `prometeu-vfs`; +5. `refresh` permanece somente manual, e `watchers` ficam explicitamente fora desta primeira decisao; +6. regras de arquivos, plugins e suporte/não-suporte pertencem ao `prometeu-vfs`; o Studio apenas apresenta o erro ou estado correspondente; +7. o nome/namespace recomendado e criar um novo modulo-base `prometeu-vfs`, deixando `prometeu-lsp` intacto como consumidor superior futuro quando a camada de protocolo existir; +8. a API oficial inicial do `prometeu-vfs` fica concentrada em RPC/comandos/queries; eventos podem existir internamente, mas nao precisam ser publicados nesta wave; +9. a `tree` do `prometeu-vfs` deve ser estrutural e de dados apenas; tree visual, estado de apresentacao e navigator chrome continuam no Studio; +10. o `Project Navigator` consome uma entidade-arvore do projeto inteiro, sem ver filesystem diretamente, mas pode solicitar atualizacoes pontuais; +11. o boundary nasce como primitive util para `studio`; hoje o editor consome, e futuramente o `prometeu-lsp` pode consumir tambem; +12. o snapshot do `prometeu-vfs` cobre apenas conteudo do projeto; +13. packer, assets e demais dominios continuam com ownership proprio e fora desse boundary, salvo decisao posterior explicita. + +Next step suggestion: converter esta agenda em uma `decision` que feche o nome do modulo-base, seu lifecycle de sessao de projeto no Studio, o contrato minimo inicial de `tree/document/RPC`, e a linha exata entre `workspace shell`, `prometeu-vfs` e um futuro `prometeu-lsp`. diff --git a/discussion/workflow/decisions/DEC-0009-studio-prometeu-vfs-project-document-boundary.md b/discussion/workflow/decisions/DEC-0009-studio-prometeu-vfs-project-document-boundary.md new file mode 100644 index 00000000..bff5fd8d --- /dev/null +++ b/discussion/workflow/decisions/DEC-0009-studio-prometeu-vfs-project-document-boundary.md @@ -0,0 +1,178 @@ +--- +id: DEC-0009 +ticket: studio-editor-document-vfs-boundary +title: Estabelecer `prometeu-vfs` como boundary documental de projeto para o Studio +status: in_progress +created: 2026-03-31 +accepted: 2026-03-31 +agenda: AGD-0012 +plans: + - PLN-0015 + - PLN-0016 + - PLN-0017 + - PLN-0018 +tags: + - studio + - editor + - workspace + - vfs + - filesystem + - boundary +--- + +## Context + +O `Code Editor` do Studio ja fechou sua primeira wave como shell editorial read-only, mas a implementacao concreta ainda instancia diretamente servicos filesystem-backed para: + +- montar a arvore estrutural do projeto; +- abrir arquivos; +- carregar conteudo de documentos; +- e aplicar regras de suporte ou nao suporte a arquivos. + +Isso mantem concerns de I/O e sincronizacao acoplados ao `EditorWorkspace`, quando o owner correto desses concerns deve ser um boundary documental de projeto. + +Tambem ficou fechado na agenda que: + +- esta etapa nao introduz novas capacidades editoriais alem das que o `EditorWorkspace` ja possui hoje; +- o estado documental precisa continuar vivo mesmo quando o `Code Editor` nao esta em foco; +- o `Project Navigator` nao deve ver filesystem diretamente; +- `prometeu-lsp` deve continuar reservado para a futura camada de protocolo/handlers; +- e packer/assets permanecem fora deste boundary. + +## Decision + +1. O repositório SHALL introduzir um novo modulo-base chamado `prometeu-vfs`. +2. `prometeu-vfs` SHALL ser o boundary documental de projeto consumido pelo Studio para `tree`, `open files` e `document content`. +3. O Studio MUST passar a tocar o disco atraves de `prometeu-vfs` para o escopo coberto por este boundary. +4. O escopo desta primeira wave MUST transportar apenas as capacidades hoje existentes no `EditorWorkspace`; nenhuma nova feature editorial SHALL ser adicionada nesta etapa. +5. `prometeu-vfs` SHALL viver no lifecycle de sessao de projeto do Studio, nao no lifecycle de foco do `EditorWorkspace`. +6. O snapshot de `prometeu-vfs` MUST cobrir apenas conteudo do projeto. +7. A `tree` exposta por `prometeu-vfs` MUST ser estrutural e de dados apenas; ela MUST NOT carregar concerns visuais ou view-model concerns de UI. +8. O `Project Navigator` do Studio SHALL consumir uma entidade que representa a arvore inteira do projeto e MAY solicitar atualizacoes mais pontuais do que um reload completo. +9. A abertura de arquivos no Studio MUST passar por `prometeu-vfs`, inclusive quando o backend concreto continuar sendo filesystem. +10. Regras de arquivos, plugins e suporte ou nao suporte MUST morar em `prometeu-vfs`; o Studio SHALL apenas apresentar o erro ou estado resultante. +11. A API oficial inicial de `prometeu-vfs` SHALL ficar concentrada em RPC/comandos/queries. +12. `prometeu-vfs` MAY manter eventos internos como parte de seu runtime, mas esses eventos MUST NOT ser publicados como API oficial nesta primeira wave. +13. `refresh` SHALL permanecer somente manual nesta primeira wave. +14. `watchers` MUST permanecer fora de escopo desta decisao e MUST NOT ser introduzidos por inferencia durante planning ou implementation. +15. `prometeu-vfs` SHALL nascer como primitive util do dominio `studio`: hoje para o editor, e futuramente podendo servir `prometeu-lsp`. +16. `prometeu-lsp` MUST permanecer como namespace/modulo separado, reservado para a futura camada de protocolo/handlers acima de `prometeu-vfs`. +17. Packer, assets e demais dominios MUST manter ownership proprio e MUST NOT ser absorvidos por `prometeu-vfs` sem decisao posterior explicita. + +## Rationale + +Esta decisao fecha a fronteira correta entre shell editorial e runtime documental. + +O Studio precisa continuar owner de: + +- layout; +- controls; +- navigator visual; +- estado de apresentacao; +- e UX de erro. + +`prometeu-vfs` precisa passar a ser owner de: + +- leitura estrutural do projeto; +- resolucao de documentos; +- abertura de arquivos; +- regras de suporte; +- refresh manual; +- e sincronizacao documental de sessao. + +Isso remove do `EditorWorkspace` um conjunto de concerns que nao pertencem ao shell. + +Criar `prometeu-vfs` como modulo novo e superior a renomear `prometeu-lsp` porque: + +- preserva a hierarquia conceitual correta; +- evita ruido editorial nos roadmaps ja existentes; +- e mantem `lsp` como consumidor futuro do substrate documental, nao como nome prematuro do substrate em si. + +Manter eventos publicos fora da primeira wave tambem e deliberado: + +- o modulo continua livre para estabilizar sua maquina interna; +- o contrato externo inicial permanece menor e mais controlado; +- e nenhum consumidor passa a depender de detalhes de runtime antes da hora. + +## Technical Specification + +### 1. Module Boundary + +- O workspace Gradle MUST incluir um novo modulo `prometeu-vfs`. +- Esse modulo SHALL ser a superficie de integracao documental do Studio para o escopo coberto por esta decisao. +- `prometeu-lsp` SHALL permanecer separado e sem reaproveitamento nominal do namespace. + +### 2. Project Session Ownership + +- A instancia principal de `prometeu-vfs` MUST pertencer a uma sessao de projeto do Studio. +- O `EditorWorkspace` MUST consumir essa instancia, e MUST NOT ser o owner do lifecycle documental. +- Troca de foco entre workspaces MUST NOT destruir o estado documental da sessao. + +### 3. Filesystem Access + +- Para o escopo coberto por esta decisao, o Studio MUST acessar o disco atraves de `prometeu-vfs`. +- O backend inicial de `prometeu-vfs` SHALL ser filesystem-backed. +- Essa decisao MUST NOT ser interpretada como criacao de um filesystem universal para todos os dominios do produto. + +### 4. Structural Tree Contract + +- `prometeu-vfs` MUST expor uma representacao estrutural do projeto inteiro. +- Essa representacao MUST incluir apenas dados e metadados estruturais/documentais necessarios ao consumo. +- Essa representacao MUST NOT conter: + - estado de expansao visual; + - selecao; + - foco; + - scroll; + - reveal; + - icones; + - ou qualquer chrome de navigator. +- O Studio MAY derivar view models visuais a partir dessa estrutura. +- O `Project Navigator` MAY solicitar atualizacoes pontuais, sem obrigar reload completo da arvore a cada interacao. + +### 5. Document and Open-File Contract + +- Abrir um arquivo no Studio MUST significar resolver esse arquivo atraves de `prometeu-vfs`. +- O conteudo de documento devolvido por `prometeu-vfs` SHALL representar apenas o estado documental do projeto dentro da sessao atual. +- Esta decisao MUST NOT ser interpretada como permissao para introduzir novas features de edicao, save, dirty tracking, merge ou write semantics. + +### 6. Support Rules and Errors + +- A determinacao de suporte ou nao suporte de um arquivo MUST ocorrer em `prometeu-vfs`. +- Regras relacionadas a plugins e resolucao de handlers de arquivo MUST morar em `prometeu-vfs`. +- O Studio SHALL apenas reagir ao resultado, exibindo erro ou estado apropriado com os mecanismos de UI existentes ou futuros. + +### 7. Communication Model + +- A API oficial inicial de `prometeu-vfs` MUST ser RPC-oriented. +- O modulo MAY manter eventos internos para coordenacao de runtime. +- Esses eventos internos MUST NOT ser expostos como API publica nesta primeira wave. +- Nenhum plano ou implementacao posterior MAY promover eventos internos a API publica por inferencia; isso exigira decisao posterior explicita. + +### 8. Refresh and Watchers + +- `refresh` SHALL permanecer manual. +- `watchers` MUST permanecer fora de escopo. +- Nenhum plano posterior MAY introduzir watching automatico por aproximacao arquitetural. + +### 9. Domain Boundaries + +- O escopo de `prometeu-vfs` SHALL permanecer restrito ao boundary documental de projeto do dominio `studio`. +- `prometeu-vfs` MUST NOT absorver responsabilidades do packer. +- `prometeu-vfs` MUST NOT redefinir ownership de assets. +- Um futuro `prometeu-lsp` MAY consumir `prometeu-vfs`, mas `prometeu-vfs` MUST NOT depender de uma camada LSP para justificar seu contrato. + +## Constraints + +- Esta decisao e normativamente travada ao escopo hoje existente no `EditorWorkspace`. +- Nenhuma feature nova de editor pode ser adicionada por conveniencia durante a migracao para `prometeu-vfs`. +- O contrato inicial deve permanecer pequeno o suficiente para planejamento e implementacao direta. +- Qualquer tentativa de: + - expor eventos publicos; + - introduzir watchers; + - ampliar o snapshot para fora do conteudo do projeto; + - ou absorver outros dominios; + exigira nova decisao explicita. + +## Revision Log + +- 2026-03-31: Initial draft from AGD-0012. diff --git a/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md b/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md new file mode 100644 index 00000000..7076f003 --- /dev/null +++ b/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md @@ -0,0 +1,156 @@ +--- +id: PLN-0015 +ticket: studio-editor-document-vfs-boundary +title: Propagate DEC-0009 into Studio shell, editor, and VFS specs +status: review +created: 2026-03-31 +completed: +tags: + - studio + - vfs + - specs + - editor + - shell +--- + +## Briefing + +Translate DEC-0009 into the normative Studio specification set before code migration starts, so the new `prometeu-vfs` boundary is explicit in shell, editor, and module-level documentation. + +## Objective + +Make the accepted `prometeu-vfs` project-document boundary normative in Studio specs without adding scope beyond the current read-only editor wave. + +## Background + +DEC-0009 locks the following architectural choices: + +- Studio accesses project-document filesystem state through `prometeu-vfs`. +- `prometeu-vfs` is project-session owned rather than editor-focus owned. +- `prometeu-vfs` exposes structural project data, not visual tree state. +- the first migration wave carries only current `EditorWorkspace` capabilities; +- manual refresh remains in scope, while watchers and public event APIs remain out of scope. + +The current spec set documents shell and editor behavior, but it does not yet define the `prometeu-vfs` boundary explicitly. + +## Dependencies + +- DEC-0009 accepted and normatively locked + +## Scope + +### Included + +- add or update Studio normative text for the `prometeu-vfs` boundary +- propagate project-session ownership rules into the shell spec +- propagate structural tree, support-rule ownership, and `prometeu-vfs` document access rules into the Code Editor spec +- update the Studio specs index if a new Studio spec is introduced + +### Excluded + +- implementation code +- public event API exposure +- watcher-based refresh +- new editor capabilities beyond the current read-only wave + +## Non-Goals + +- redesign the shell +- define a public event catalog for `prometeu-vfs` +- generalize `prometeu-vfs` into a product-wide filesystem abstraction + +## Execution Method + +### Step 1 - Introduce a Normative `prometeu-vfs` Boundary Spec + +**What:** +Create a dedicated Studio spec for the project-document boundary so DEC-0009 does not have to be split awkwardly across unrelated shell and editor documents. + +**How:** +Add a new Studio spec that defines: + +- `prometeu-vfs` module role +- project-session ownership +- filesystem-backed first-wave contract +- structural tree contract +- RPC-first public API baseline +- manual refresh rule +- non-goals for public events and watchers + +**File(s):** +- `docs/specs/studio/6. Project Document VFS Specification.md` + +### Step 2 - Propagate Session Ownership into the Shell Spec + +**What:** +Update shell-level architecture rules so the shell explicitly owns project-session services that survive workspace focus changes. + +**How:** +Amend the shell spec to state that workspace-local composition may consume project-session-owned services such as `prometeu-vfs`, while shell/workspace responsibility boundaries remain intact. + +**File(s):** +- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` + +### Step 3 - Propagate Editor-Local Boundary Rules + +**What:** +Update the Code Editor spec so all project-tree and document access rules point to `prometeu-vfs` instead of direct filesystem readers inside the workspace. + +**How:** +Amend the editor spec to state that: + +- the navigator consumes a structural tree entity provided by `prometeu-vfs` +- the editor opens files through `prometeu-vfs` +- support and unsupported-file rules belong to `prometeu-vfs` +- visual tree state remains in Studio UI +- refresh remains manual + +**File(s):** +- `docs/specs/studio/5. Code Editor Workspace Specification.md` + +### Step 4 - Update the Studio Spec Index + +**What:** +Keep the Studio spec corpus discoverable after adding the new boundary spec. + +**How:** +Update the index/read-order document to include the new `prometeu-vfs` spec and place it in a reading order that preserves shell -> shared boundary -> workspace detail. + +**File(s):** +- `docs/specs/studio/README.md` + +## Test Requirements + +### Unit Tests + +- none + +### Integration Tests + +- none + +### Manual Verification + +- verify the new spec set contains no contradiction between shell ownership, `prometeu-vfs` ownership, and Code Editor ownership +- verify the new spec wording does not introduce watchers, public events, write semantics, or non-project content by implication + +## Acceptance Criteria + +- [ ] DEC-0009 is fully represented in the Studio spec corpus without reopening the agenda +- [ ] shell, `prometeu-vfs`, and editor responsibilities are separated unambiguously +- [ ] the spec set states that `prometeu-vfs` provides structural data only, not visual tree state +- [ ] the spec set states that the first wave remains limited to current editor capabilities +- [ ] the spec set states that refresh is manual and watchers remain out of scope + +## Affected Artifacts + +- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` +- `docs/specs/studio/5. Code Editor Workspace Specification.md` +- `docs/specs/studio/6. Project Document VFS Specification.md` +- `docs/specs/studio/README.md` + +## Risks + +- splitting the rules across too many documents could make the boundary harder to follow +- forcing all rules into the editor spec could bury project-session ownership in a workspace-local document +- imprecise wording here would leak directly into implementation scope diff --git a/discussion/workflow/plans/PLN-0016-build-prometeu-vfs-filesystem-backed-core.md b/discussion/workflow/plans/PLN-0016-build-prometeu-vfs-filesystem-backed-core.md new file mode 100644 index 00000000..1ae32aa5 --- /dev/null +++ b/discussion/workflow/plans/PLN-0016-build-prometeu-vfs-filesystem-backed-core.md @@ -0,0 +1,185 @@ +--- +id: PLN-0016 +ticket: studio-editor-document-vfs-boundary +title: Build the filesystem-backed `prometeu-vfs` core for project tree and documents +status: review +created: 2026-03-31 +completed: +tags: + - studio + - vfs + - filesystem + - rpc + - module +--- + +## Briefing + +Create the first `prometeu-vfs` module implementation as a filesystem-backed project-document core that carries only the current Code Editor capabilities. + +## Objective + +Introduce a testable `prometeu-vfs` module that owns structural project snapshots, document loading, support classification, and manual refresh operations for project content. + +## Background + +The current editor owns three separate local responsibilities: + +- project tree snapshot building +- file buffer loading and unsupported-file classification +- session-local opened-file coordination + +DEC-0009 moves the first two responsibilities into `prometeu-vfs` while preserving the current functional surface and deferring watchers, public events, and write semantics. + +## Dependencies + +- DEC-0009 accepted and normatively locked +- PLN-0015 accepted or otherwise completed enough to make the target spec language stable + +## Scope + +### Included + +- add the new Gradle module wiring for `prometeu-vfs` +- define the initial RPC-oriented public API for project tree and document access +- implement a filesystem-backed first version +- move file support classification into `prometeu-vfs` +- add unit tests that cover the new module behavior + +### Excluded + +- project-session ownership in Studio bootstrap +- workspace UI changes beyond dependency wiring needed for compilation +- public event API exposure +- watchers +- save, dirty tracking, writes, merge handling, or conflict handling +- non-project content snapshots + +## Non-Goals + +- create a general VFS for packer, assets, or debugger +- redesign the editor session model +- introduce a second backend beyond filesystem + +## Execution Method + +### Step 1 - Add `prometeu-vfs` to the Gradle Workspace + +**What:** +Make the new module part of the build and available to Studio code. + +**How:** +Update the root Gradle settings and module dependencies so the Studio can compile against `prometeu-vfs`. + +**File(s):** +- `settings.gradle.kts` +- `prometeu-studio/build.gradle.kts` +- new `prometeu-vfs/**` + +### Step 2 - Define the Initial RPC-Oriented Contract + +**What:** +Create the public API surface for structural tree retrieval, point refresh requests, document resolution, and support classification. + +**How:** +Define models and service interfaces in `prometeu-vfs` for: + +- project-scoped tree snapshots +- structural tree nodes +- document open/load results +- unsupported-file or unsupported-handler outcomes +- manual refresh commands, including targeted refresh requests for narrower scope than full reload + +The API must remain RPC-oriented and must not expose public events in this wave. + +**File(s):** +- new `prometeu-vfs/src/main/java/p/studio/vfs/**` + +### Step 3 - Implement the Filesystem-Backed First Version + +**What:** +Move direct filesystem behavior out of editor-local services and into `prometeu-vfs`. + +**How:** +Implement the first module version using filesystem access for: + +- full-project structural snapshot construction +- folder-first alphabetical ordering +- project-only scope +- UTF-8 text loading +- binary or unsupported-file rejection +- support-rule evaluation + +Port the logic now living in: + +- `EditorProjectSnapshotService` +- `EditorFileBufferLoader` + +without adding new end-user behavior. + +**File(s):** +- new `prometeu-vfs/src/main/java/p/studio/vfs/**` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java` + +### Step 4 - Move Core Tests to the Module Boundary + +**What:** +Place structural snapshot and document-loading tests at the new ownership boundary. + +**How:** +Port and expand the current editor service tests into `prometeu-vfs` module tests, covering: + +- hidden file inclusion +- folder-first ordering +- project-only root handling +- unsupported file outcomes +- UTF-8 and NUL-byte handling +- targeted refresh request behavior + +**File(s):** +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java` +- new `prometeu-vfs/src/test/java/p/studio/vfs/**` + +## Test Requirements + +### Unit Tests + +- structural tree snapshot coverage +- document load and unsupported-file coverage +- targeted refresh request coverage +- project-only scope coverage + +### Integration Tests + +- module-level integration test that builds a snapshot and resolves documents from a test project root + +### Manual Verification + +- verify the module can build against Studio without introducing UI dependencies +- verify no public event API leaks into the first-wave contract + +## Acceptance Criteria + +- [ ] the build contains a new `prometeu-vfs` module wired into Studio +- [ ] project tree and document loading behavior now exist in `prometeu-vfs` +- [ ] the public contract is RPC-oriented and does not expose public events +- [ ] unsupported-file classification is owned by `prometeu-vfs` +- [ ] module tests cover the current editor-visible filesystem behavior + +## Affected Artifacts + +- `settings.gradle.kts` +- `prometeu-studio/build.gradle.kts` +- new `prometeu-vfs/**` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java` + +## Risks + +- overfitting the first API to current editor internals could make later Studio and LSP consumers awkward +- keeping too much logic in the editor during migration would weaken the ownership boundary +- adding too much abstraction now would violate the first-wave scope limit diff --git a/discussion/workflow/plans/PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md b/discussion/workflow/plans/PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md new file mode 100644 index 00000000..3b7183ea --- /dev/null +++ b/discussion/workflow/plans/PLN-0017-add-studio-project-session-ownership-for-prometeu-vfs.md @@ -0,0 +1,153 @@ +--- +id: PLN-0017 +ticket: studio-editor-document-vfs-boundary +title: Add Studio project-session ownership for `prometeu-vfs` +status: review +created: 2026-03-31 +completed: +tags: + - studio + - vfs + - project-session + - shell + - lifecycle +--- + +## Briefing + +Move `prometeu-vfs` ownership into the Studio project session so document state survives workspace focus changes and is not owned by `EditorWorkspace`. + +## Objective + +Create a project-session integration path in Studio that constructs, passes, and disposes `prometeu-vfs` state outside workspace focus transitions. + +## Background + +DEC-0009 requires `prometeu-vfs` to live at project-session scope rather than editor-workspace scope. The current project-open path builds a `MainView` directly from `ProjectReference` and has no dedicated project-session service layer for editor document runtime state. + +## Dependencies + +- DEC-0009 accepted and normatively locked +- PLN-0016 accepted or otherwise completed enough to provide the `prometeu-vfs` contract + +## Scope + +### Included + +- add a Studio-side project-session owner for `prometeu-vfs` +- construct that session during project open +- keep the session alive while the project window is open +- dispose the session when the project window closes +- pass the session or a focused `prometeu-vfs` facade down to `MainView` and workspace consumers + +### Excluded + +- editor behavior changes beyond consuming the new session-owned dependency +- public event API exposure +- watchers +- shared product-wide session framework beyond what this boundary needs + +## Non-Goals + +- move packer ownership into the same session abstraction +- create a multi-project global VFS cache +- redesign the project launcher UX + +## Execution Method + +### Step 1 - Introduce a Studio Project-Session Holder for `prometeu-vfs` + +**What:** +Create the Studio-side owner that keeps `prometeu-vfs` alive for the lifetime of an opened project window. + +**How:** +Add a project-session abstraction or holder in `prometeu-studio` that stores: + +- the `ProjectReference` +- the session-owned `prometeu-vfs` instance or facade +- shutdown/close behavior + +This holder must not be tied to workspace focus. + +**File(s):** +- new `prometeu-studio/src/main/java/p/studio/projectsessions/**` +- `prometeu-studio/src/main/java/p/studio/Container.java` + +### Step 2 - Wire Session Creation into the Project Open Path + +**What:** +Construct and dispose the project-session-owned `prometeu-vfs` at the same level where the project window lifecycle is managed. + +**How:** +Update project-open flow so `StudioWindowCoordinator` creates the project session before the main window is shown and closes it when the project window is torn down. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java` +- `prometeu-app/src/main/java/p/studio/AppContainer.java` + +### Step 3 - Pass the Session into the Main Shell + +**What:** +Make the project-session-owned `prometeu-vfs` available to shell consumers without making the container globally own per-project state. + +**How:** +Update `MainView` construction and related shell wiring so project-scoped consumers receive the session-owned dependency explicitly. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/window/MainView.java` +- new `prometeu-studio/src/main/java/p/studio/projectsessions/**` + +### Step 4 - Add Session Lifecycle Tests + +**What:** +Verify that `prometeu-vfs` lifecycle follows project-window lifetime rather than workspace focus changes. + +**How:** +Add tests that cover: + +- session creation on project open +- session reuse while switching workspaces +- session shutdown on project window close + +**File(s):** +- new `prometeu-studio/src/test/java/p/studio/projectsessions/**` +- new `prometeu-studio/src/test/java/p/studio/window/**` + +## Test Requirements + +### Unit Tests + +- session holder lifecycle behavior +- shutdown behavior + +### Integration Tests + +- coordinator-level test for project-open and project-close lifecycle + +### Manual Verification + +- open a project, switch between workspaces, and confirm document state is not recreated by workspace focus changes +- close the project window and confirm project-session resources are released + +## Acceptance Criteria + +- [ ] `prometeu-vfs` is owned by a Studio project session rather than `EditorWorkspace` +- [ ] opening a project creates the session before normal editor consumption +- [ ] workspace focus changes do not destroy the project-document state +- [ ] closing the project window releases session-owned resources + +## Affected Artifacts + +- `prometeu-studio/src/main/java/p/studio/Container.java` +- `prometeu-app/src/main/java/p/studio/AppContainer.java` +- `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java` +- `prometeu-studio/src/main/java/p/studio/window/MainView.java` +- new `prometeu-studio/src/main/java/p/studio/projectsessions/**` +- new `prometeu-studio/src/test/java/p/studio/projectsessions/**` +- new `prometeu-studio/src/test/java/p/studio/window/**` + +## Risks + +- letting the container own per-project state globally would collapse window boundaries +- placing ownership too low in the shell would recreate the same focus-coupling problem under a different name +- weak disposal semantics would leak project-session resources after window close diff --git a/discussion/workflow/plans/PLN-0018-migrate-code-editor-to-prometeu-vfs.md b/discussion/workflow/plans/PLN-0018-migrate-code-editor-to-prometeu-vfs.md new file mode 100644 index 00000000..1ca3989e --- /dev/null +++ b/discussion/workflow/plans/PLN-0018-migrate-code-editor-to-prometeu-vfs.md @@ -0,0 +1,168 @@ +--- +id: PLN-0018 +ticket: studio-editor-document-vfs-boundary +title: Migrate the Code Editor workspace to consume `prometeu-vfs` +status: review +created: 2026-03-31 +completed: +tags: + - studio + - editor + - vfs + - migration + - tests +--- + +## Briefing + +Replace direct editor-local filesystem services with `prometeu-vfs` while preserving current read-only behavior, current unsupported-file UX, and current session-local open-tab behavior. + +## Objective + +Make the Code Editor workspace consume the project-session-owned `prometeu-vfs` for tree and document access without changing the visible behavior of the current editor wave. + +## Background + +The editor currently wires `EditorProjectSnapshotService` and `EditorFileBufferLoader` directly into `EditorWorkspace`. DEC-0009 requires those concerns to move behind `prometeu-vfs`, while the editor remains owner of layout, visual tree state, open-tab presentation, and error presentation. + +## Dependencies + +- DEC-0009 accepted and normatively locked +- PLN-0016 accepted or otherwise completed enough to provide the new module contract +- PLN-0017 accepted or otherwise completed enough to provide project-session ownership + +## Scope + +### Included + +- update `EditorWorkspace` to consume `prometeu-vfs` instead of direct filesystem services +- preserve existing `EditorOpenFileSession` ownership for session-local tab state +- preserve the existing unsupported-file modal behavior while moving support determination into `prometeu-vfs` +- remove or retire editor-local filesystem services whose ownership moved into `prometeu-vfs` +- adjust tests accordingly + +### Excluded + +- write support +- dirty tracking +- watchers +- public event API exposure +- visual redesign of the editor + +## Non-Goals + +- replace `EditorOpenFileSession` +- introduce outline semantics or helper-region behavior +- change the supported-file UX from modal to another surface + +## Execution Method + +### Step 1 - Rewire Editor Construction Around `prometeu-vfs` + +**What:** +Inject the project-session-owned `prometeu-vfs` dependency into the editor workspace and route tree/document actions through it. + +**How:** +Update shell/editor construction so `EditorWorkspace` receives the `prometeu-vfs` consumer dependency it needs and uses it for: + +- navigator refresh +- file open +- support resolution + +while keeping `EditorOpenFileSession` as the owner of open-tab presentation state. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/window/MainView.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java` + +### Step 2 - Remove Direct Filesystem Ownership from the Editor + +**What:** +Stop the editor package from owning project-tree and document-loading filesystem code. + +**How:** +Delete, deprecate, or reduce editor-local classes once their behavior lives in `prometeu-vfs`, ensuring no direct filesystem responsibility remains in the editor workspace boundary for those concerns. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshot.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNode.java` + +### Step 3 - Preserve Visual Ownership in the Navigator and Status Surfaces + +**What:** +Keep the Studio UI responsible for presentation and view-model concerns after the data-source migration. + +**How:** +Update navigator/status consumers to derive their presentation state from `prometeu-vfs` structural data without moving visual state into the module boundary. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNavigatorPanel.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspaceIcons.java` + +### Step 4 - Rebalance the Test Suite Around the New Ownership Boundary + +**What:** +Keep editor tests focused on editor-owned behavior after tree/document ownership moves to `prometeu-vfs`. + +**How:** + +- keep `EditorOpenFileSessionTest` for tab/session behavior +- move filesystem behavior tests to `prometeu-vfs` +- add editor-facing tests where necessary for VFS integration, unsupported-file modal routing, and refresh wiring + +**File(s):** +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorOpenFileSessionTest.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java` +- new `prometeu-studio/src/test/java/p/studio/workspaces/editor/**` + +## Test Requirements + +### Unit Tests + +- editor session/tab behavior remains covered +- unsupported-file modal routing remains covered if testable at this layer +- no editor-local tree/document filesystem tests remain after migration + +### Integration Tests + +- editor workspace integration test using a project-session-owned `prometeu-vfs` dependency + +### Manual Verification + +- open a project and confirm the navigator still shows the whole project +- use manual refresh and confirm the editor tree updates through `prometeu-vfs` +- open supported text files and confirm content still appears read-only +- open unsupported files and confirm the existing modal behavior remains intact + +## Acceptance Criteria + +- [ ] `EditorWorkspace` no longer instantiates direct filesystem tree/document loaders +- [ ] current read-only editor behavior remains unchanged from the user perspective +- [ ] unsupported-file handling still appears through Studio UI while support classification lives in `prometeu-vfs` +- [ ] editor tests now cover editor-owned behavior rather than filesystem ownership that moved to `prometeu-vfs` + +## Affected Artifacts + +- `prometeu-studio/src/main/java/p/studio/window/MainView.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorFileBufferLoader.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshot.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNode.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectNavigatorPanel.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorOpenFileSessionTest.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorProjectSnapshotServiceTest.java` +- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorFileBufferLoaderTest.java` +- new `prometeu-studio/src/test/java/p/studio/workspaces/editor/**` + +## Risks + +- a shallow adapter-only migration could leave hidden direct filesystem access in the editor package +- moving too much presentation logic into `prometeu-vfs` would violate DEC-0009 +- changing unsupported-file UX during the migration would exceed the first-wave scope diff --git a/test-projects/fragments/.studio/activities.json b/test-projects/fragments/.studio/activities.json index ed82ed58..ba7f3dc9 100644 --- a/test-projects/fragments/.studio/activities.json +++ b/test-projects/fragments/.studio/activities.json @@ -178,6 +178,16 @@ "message" : "Asset scan started", "severity" : "INFO", "sticky" : false +}, { + "source" : "Assets", + "message" : "0 assets loaded", + "severity" : "SUCCESS", + "sticky" : false +}, { + "source" : "Assets", + "message" : "Asset scan started", + "severity" : "INFO", + "sticky" : false }, { "source" : "Studio", "message" : "Project ready",