From be3eaaf4cfc83f0575677fe5c3eda62902fb86c2 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 12 Mar 2026 09:03:42 +0000 Subject: [PATCH] activity PR added --- ...d-studio-state-and-activity-persistence.md | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md diff --git a/docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md b/docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md new file mode 100644 index 00000000..475784ad --- /dev/null +++ b/docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md @@ -0,0 +1,111 @@ +# PR-06 Project-Scoped Studio State and Activity Persistence + +Domain owner: `docs/studio` + +## Briefing + +Move Studio-local project persistence under each project root and make shell activity durable per project. + +The target model is: + +- each project owns a `.studio/` directory; +- `.studio/` is created when a new project is created; +- shell activity is stored inside that project-local directory and restored when the project is opened; +- activity retention is capped at a fixed maximum of `500` entries; +- the same `.studio/` root becomes the reserved home for future Studio project configuration. + +## Objective + +Make Studio state project-scoped instead of application-global where the data is inherently tied to one project, starting with activity persistence and the project-local Studio storage root. + +After this change: + +- opening a project reloads its recent activity feed; +- new activity entries are appended to that project's persisted history; +- persisted history is trimmed to the latest `500` entries; +- newly created projects already contain the `.studio/` structure expected by Studio. + +## Dependencies + +- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) +- current project creation flow in `ProjectCatalogService` +- current shell activity mapping and rendering in `StudioActivityFeedControl` + +## Scope + +- define the project-local Studio storage convention under `.studio/` +- persist shell activity entries per project +- restore persisted activity when a project shell opens +- enforce a hard retention cap of `500` entries +- create `.studio/` during new-project scaffolding +- reserve `.studio/` as the home for future project-local Studio settings +- replace the current scaffolded `.workspace/` directory with `.studio/` + +## Non-Goals + +- no redesign of activity event semantics or severity mapping +- no cross-project merged activity history +- no migration of global launcher data such as known projects +- no broad persistence pass for every workspace in this PR +- no attempt to define every future file that may live under `.studio/` + +## Execution Method + +1. Define the `.studio/` storage contract for Studio-owned project data. + Proposed baseline layout: + - `.studio/activities.json` for persisted shell activity history + - `.studio/settings.json` reserved for project-local Studio configuration + +2. Introduce a small project-local storage path abstraction. + It should centralize resolution of `.studio/`, activity storage, and future settings storage from `ProjectReference.rootPath()`. + +3. Add an activity persistence service/repository. + Responsibilities: + - load persisted entries for a project; + - store entries after append; + - normalize malformed or missing files into an empty history; + - trim persisted and in-memory history to the latest `500` records. + +4. Refactor `StudioActivityFeedControl` to become project-aware at construction time. + The control should: + - hydrate its initial list from persisted project activity; + - append new mapped entries to memory and persistence; + - preserve the existing duplicate-suppression behavior unless it conflicts with durable history expectations. + +5. Update shell composition to pass the active `ProjectReference` into the activity feed. + `MainView` should instantiate the feed for the currently opened project instead of a project-agnostic global feed. + +6. Update project creation scaffolding. + `ProjectCatalogService.createProject(...)` must create `.studio/` and stop creating `.workspace/`. + If needed, opening an older project may lazily create `.studio/` on first persistence write. + +7. Propagate the contract to Studio specs and tests. + The shell spec should state that shell activity is project-scoped, restored on open, and retained with a bounded history. + +## Acceptance Criteria + +- opening a project with an existing `.studio/activities.json` restores that project's recent activity feed before new events arrive +- activity produced while a project is open is persisted under that project's `.studio/` directory +- persisted activity history never exceeds `500` entries +- newly created projects contain `.studio/` +- new-project tests no longer expect `.workspace/` +- opening a project without `.studio/activities.json` still works and initializes an empty feed + +## Validation + +- unit tests for project scaffolding asserting `.studio/` creation +- unit tests for activity storage load/save behavior +- unit tests for retention trimming to `500` +- unit tests for activity-feed hydration from persisted entries +- unit tests for malformed or missing activity storage fallback +- smoke validation opening two different projects and confirming isolated activity histories + +## Affected Artifacts + +- `prometeu-studio/src/main/java/p/studio/projects/ProjectCatalogService.java` +- `prometeu-studio/src/main/java/p/studio/window/MainView.java` +- `prometeu-studio/src/main/java/p/studio/controls/shell/StudioActivityFeedControl.java` +- new Studio project-storage service/repository classes under `prometeu-studio/src/main/java/p/studio/...` +- `prometeu-studio/src/test/java/p/studio/projects/ProjectCatalogServiceTest.java` +- new activity persistence tests under `prometeu-studio/src/test/java/p/studio/...` +- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`