prometeu-vsf

This commit is contained in:
2026-03-31 08:00:10 +01:00
parent d9ba5e3cb4
commit 0f056a1ea1
8 changed files with 1052 additions and 1 deletions
@@ -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
@@ -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
@@ -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
@@ -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