housekeep

This commit is contained in:
2026-04-07 05:33:18 +01:00
parent 49b2715158
commit 5b03fe6cfd
13 changed files with 58 additions and 1437 deletions
@@ -1,96 +0,0 @@
---
id: PLN-0041
ticket: studio-play-stop-cartridge-flow
title: Ordered Plan 1 - Shipper preparation foundation for build, pack, and manifest
status: review
created: 2026-04-06
completed:
tags: [studio, play-stop, shipper, build, pack, manifest]
---
## Objective
Implement the Studio shipper service as the owner of preparation orchestration for `build -> pack-validation -> pack -> manifest`, with deterministic output in `build/`.
## Background
`DEC-0020` establishes that preparation is Studio-owned, that `build/` is the runnable artifact root, and that shipper owns preparation orchestration plus aggregation of preparation logs.
This is the first and foundational plan in the family. Later plans depend on its service boundary and result contracts.
## Scope
### Included
- Introduce or reshape a Studio-owned shipper service boundary.
- Execute `build`, pack validation, `pack`, and manifest generation in the required order.
- Produce deterministic preparation results and failure boundaries.
- Preserve preparation log channels `build`, `pack-validation`, and `pack`.
### Excluded
- External runtime spawning.
- Debugger workspace UI.
- Runtime handshake.
- Drift/freshness reuse logic.
## Execution Steps
### Step 1 - Define the shipper service contract
**What:** Add a Studio-owned service/API for preparation that exposes ordered preparation, result status, and preparation-log output.
**How:** Introduce dedicated types for preparation request/result and channel-aware preparation log entries. Keep the service independent from UI controls and workspaces.
**File(s):** `prometeu-studio/src/main/java/p/studio/.../shipper/*` (new package), existing `ShipperWorkspace` call sites as adapters only.
### Step 2 - Implement ordered preparation
**What:** Execute compiler build, pack validation, pack, and manifest generation through the shipper service.
**How:** Reuse existing compiler and packer entrypoints. Enforce stop-on-first-failure. Do not introduce cancellation. Ensure pack validation blocks pack when needed.
**File(s):** `prometeu-studio` service layer, packer integration call sites, manifest generation implementation.
### Step 3 - Materialize the deterministic build contract
**What:** Ensure successful preparation leaves `build/program.pbx`, `build/assets.pa`, and `build/manifest.json` in the expected state.
**How:** Keep compiler and packer domain ownership of their artifacts, but make manifest generation part of shipper success. Preserve the absence of a separate `cartridge/` root.
**File(s):** shipper implementation, manifest-generation code, any preparation DTOs/results.
### Step 4 - Publish channel-preserving preparation output
**What:** Aggregate preparation output for downstream consumption while preserving per-channel identity.
**How:** Build a merged-but-structured stream that labels entries as `build`, `pack-validation`, or `pack`. Expose it as shipper-owned output rather than UI-owned state.
**File(s):** shipper service/result/log types, adapters from compiler and packer logs.
## Test Requirements
### Unit Tests
- Verify shipper enforces the exact order `build -> pack-validation -> pack -> manifest`.
- Verify pack validation failure stops the flow before pack.
- Verify manifest generation only happens after successful build and pack.
- Verify aggregated preparation logs preserve the three required source channels.
### Integration Tests
- Exercise a successful preparation flow against a real project fixture and assert expected files exist in `build/`.
- Exercise build failure and assert pack and manifest are skipped.
- Exercise pack-validation failure and assert pack and manifest are skipped.
### Manual Verification
- Trigger shipper preparation on a real Studio project and confirm `build/` contains the expected artifacts.
- Inspect emitted preparation logs and confirm channel labels remain visible.
## Acceptance Criteria
- [ ] A Studio-owned shipper service exists and is the sole owner of preparation orchestration.
- [ ] Preparation executes in the exact decision-ordered sequence.
- [ ] Preparation stops on first failure and does not support cancellation in this wave.
- [ ] Successful preparation leaves the required runnable files in `build/`.
- [ ] Preparation output preserves `build`, `pack-validation`, and `pack` channel identity.
## Dependencies
- Accepted `DEC-0020`.
- Existing compiler `build` entrypoint.
- Existing packer validation and pack entrypoints.
## Risks
- Hidden coupling to the current `ShipperWorkspace` scratch path may leak UI assumptions into the service boundary.
- Manifest generation may become entangled with runtime policy if not kept narrow.
- Log aggregation may collapse source identity if implemented as raw text concatenation.
@@ -1,91 +0,0 @@
---
id: PLN-0042
ticket: studio-play-stop-cartridge-flow
title: Ordered Plan 2 - Shared execution session and merged log contracts
status: review
created: 2026-04-06
completed:
tags: [studio, play-stop, debugger, session, logs, state]
---
## Objective
Define and implement the shared execution-session boundary that exists outside visual workspace lifecycle and carries state plus merged log contracts for preparation and runtime.
## Background
`DEC-0021` and `DEC-0022` require a shared state machine and a merged log destination independent of the visual `DebugWorkspace`. `DEC-0020` requires shipper-owned preparation log aggregation.
This plan is intentionally cross-cutting and must land before the final orchestration and workspace consumption plans.
## Scope
### Included
- Shared session/service boundary outside the visual workspace.
- Minimum shared state machine: `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, `stopped`.
- Structured merged log-entry contract with visible source identity.
- Adapters for shipper-owned preparation output and runtime output to feed the shared session.
### Excluded
- Final debugger workspace UI.
- Runtime process spawning details.
- Full handshake implementation details.
- Profiler behavior.
## Execution Steps
### Step 1 - Define shared state and session contracts
**What:** Introduce shared types and services for execution-session state.
**How:** Create a Studio-owned session/service API not tied to `Workspace` lifecycle. Add explicit transitions for the minimum required states.
**File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent shared execution package.
### Step 2 - Define merged log-entry contracts
**What:** Add a structured log-entry model for merged execution logs.
**How:** Require at least `source`, `message`, `severity`, and ordering metadata such as timestamp/sequence. Preserve the source channels `build`, `pack-validation`, `pack`, and `runtime`.
**File(s):** shared execution/debug model package, service interfaces, DTOs/events.
### Step 3 - Connect shipper output to the shared session
**What:** Feed shipper-owned preparation output into the shared session boundary.
**How:** Adapt the shipper result/log stream into session log entries and preparation state transitions without moving ownership away from shipper.
**File(s):** shipper adapters, shared session service, orchestration glue.
### Step 4 - Connect runtime output to the shared session
**What:** Reserve the runtime side of the merged stream and state transitions for later orchestration plans.
**How:** Define append/update APIs now so later runtime plans can publish `connecting`, `running`, `runtime_failed`, and `stopped` without changing the contract shape.
**File(s):** shared session/service types and tests.
## Test Requirements
### Unit Tests
- Verify legal state transitions for the minimum state machine.
- Verify merged log entries preserve source identity and ordering metadata.
- Verify shipper output can be appended without collapsing channels.
### Integration Tests
- Feed a simulated preparation success/failure sequence into the shared session and assert resulting state and log stream.
- Verify the shared session survives workspace recreation or absence.
### Manual Verification
- Inspect a development build and confirm execution state remains available even if the visual debug surface is not yet mounted.
## Acceptance Criteria
- [ ] A shared execution-session service exists outside the visual workspace lifecycle.
- [ ] The minimum state machine is explicitly implemented.
- [ ] Merged log entries preserve source identity for `build`, `pack-validation`, `pack`, and `runtime`.
- [ ] Shipper preparation output can flow into the shared session without changing shipper ownership.
## Dependencies
- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
- `PLN-0041` shipper preparation foundation.
## Risks
- State transitions may become duplicated between shell, workspace, and service if ownership is not kept strict.
- Log models that are too thin will force churn once the debugger surface exists.
- Overdesign here could slow down the simple first wave the decisions explicitly allow.
@@ -1,90 +0,0 @@
---
id: PLN-0043
ticket: studio-debugger-workspace-integration
title: Ordered Plan 3 - First-wave DebugWorkspace registration and temporary execution surface
status: review
created: 2026-04-06
completed:
tags: [studio, debugger, workspace, logs, shell]
---
## Objective
Register a native `DebugWorkspace` in Studio and provide a first-wave temporary execution surface that consumes shared session state and merged logs.
## Background
`DEC-0022` requires a real native workspace, not an external launcher. `DEC-0021` requires `Play` to navigate toward the debugger destination at the start of execution.
This plan intentionally keeps the UI crude and execution-focused.
## Scope
### Included
- Register a concrete `DebugWorkspace` in the Studio shell.
- Consume the shared session/service boundary from `PLN-0042`.
- Render simple session state and a simple merged log sink with visible source labels.
- Provide a temporary but native in-Studio execution destination.
### Excluded
- Polished final debugger UX.
- Rich manual connect/disconnect controls.
- Profiler behavior.
- Standalone debugger bootstrap embedding.
## Execution Steps
### Step 1 - Register the workspace in the shell
**What:** Make `WorkspaceId.DEBUG` point to a real workspace implementation.
**How:** Add and register a native `DebugWorkspace` that follows Studio workspace lifecycle and event-bus rules.
**File(s):** `prometeu-studio/src/main/java/p/studio/window/MainView.java`, `prometeu-studio/src/main/java/p/studio/workspaces/.../DebugWorkspace.java` (new).
### Step 2 - Add first-wave session state presentation
**What:** Surface the shared session states in the workspace.
**How:** Render a simple status area or equivalent control showing at least `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, and `stopped`.
**File(s):** `DebugWorkspace` controls and supporting view models/bindings.
### Step 3 - Add the temporary merged log sink
**What:** Show merged execution logs in a simple native Studio surface.
**How:** Use a list/console style control with visible source labels and lightweight severity treatment. Consume the shared session log stream from `PLN-0042`.
**File(s):** `DebugWorkspace` controls, log pane/control package.
### Step 4 - Preserve native Studio shape
**What:** Keep lifecycle, theming, i18n, and shell-navigation compliance.
**How:** Avoid importing the standalone debugger host/bootstrap. Use only Studio-native workspace composition.
**File(s):** workspace implementation, i18n keys, theme/style files as needed.
## Test Requirements
### Unit Tests
- Verify the workspace can consume session state updates and reflect them.
- Verify merged log entries render with visible source identity.
### Integration Tests
- Mount the workspace in a shell test and confirm it registers without throwing.
- Feed synthetic session/log events and confirm the workspace updates without owning the underlying state.
### Manual Verification
- Open the `Debug` workspace from the Studio shell.
- Confirm session states and merged logs are visible in a simple but usable surface.
## Acceptance Criteria
- [ ] `WorkspaceId.DEBUG` resolves to a real native workspace.
- [ ] The workspace shows shared execution state.
- [ ] The workspace shows merged logs with visible source identity.
- [ ] The implementation stays within native Studio workspace boundaries.
## Dependencies
- Accepted `DEC-0022`.
- `PLN-0042` shared execution session and log contracts.
## Risks
- The first-wave UI may accidentally hardcode temporary choices that later feel permanent.
- Workspace ownership may drift into session ownership if bindings are not kept one-way.
@@ -1,80 +0,0 @@
---
id: PLN-0044
ticket: studio-debugger-workspace-integration
title: Ordered Plan 4 - Runtime handshake integration from selective debugger knowledge
status: review
created: 2026-04-06
completed:
tags: [studio, debugger, runtime, handshake, remote-connection]
---
## Objective
Integrate the minimum runtime/debug-session handshake needed for the current flow, using selective knowledge from `../debugger` without creating a project linkage.
## Background
`DEC-0022` allows handshake details to be derived from `../debugger` while keeping Studio-native boundaries. `DEC-0021` reserves `debug` for the future but requires enough session behavior to support the current `run` flow and debugger destination.
## Scope
### Included
- Study and selectively port the useful runtime-handshake behavior from `../debugger`.
- Implement Studio-native handshake/session integration code.
- Publish handshake state into the shared execution session boundary.
### Excluded
- Composite build or live dependency on `../debugger`.
- Full debugger feature parity.
- Profiler behavior.
- Manual rich connection-control UI.
## Execution Steps
### Step 1 - Identify the useful handshake slice
**What:** Isolate the exact handshake/protocol/session behavior needed from `../debugger`.
**How:** Read the sibling repo and extract only the minimum details necessary for the current run/debug-session handshake. Do not mirror the standalone app structure.
**File(s):** Study `../debugger`; implement only Studio-native targets under `prometeu-studio`.
### Step 2 - Implement a Studio-native handshake service
**What:** Add handshake/session integration code in Studio-native shape.
**How:** Create a dedicated service or adapter layer that can publish `connecting`, `connected`, and failure information into the shared execution session.
**File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent service package.
### Step 3 - Connect the handshake to the shared session
**What:** Make handshake outcomes visible to shell and workspace consumers.
**How:** Feed successful and failed handshake events into the session state machine and merged logs without requiring the visual workspace to own the protocol.
**File(s):** shared session service, handshake adapter/service, tests.
## Test Requirements
### Unit Tests
- Verify handshake success updates the shared session to the expected connected/running path.
- Verify handshake failure updates the shared session to a failure state and emits visible log output.
### Integration Tests
- Simulate the runtime handshake sequence and confirm session consumers receive the expected state transitions.
### Manual Verification
- Run a development build and confirm the session reflects connecting/connected/failed without needing the standalone debugger app.
## Acceptance Criteria
- [ ] Studio contains a native handshake/service implementation shaped for the current flow.
- [ ] No technical linkage to `../debugger` is introduced.
- [ ] Shared session state reflects handshake success and failure.
- [ ] The implementation selectively reuses useful debugger knowledge without wholesale copying.
## Dependencies
- Accepted `DEC-0021` and `DEC-0022`.
- `PLN-0042` shared execution session and log contracts.
- `PLN-0043` first-wave debug workspace surface.
## Risks
- Porting too much from `../debugger` could drag standalone assumptions into Studio.
- Porting too little may leave the current flow without a stable enough handshake.
@@ -1,108 +0,0 @@
---
id: PLN-0045
ticket: studio-play-stop-cartridge-flow
title: Ordered Plan 5 - End-to-end Play/Stop execution flow through shipper and DebugWorkspace
status: review
created: 2026-04-06
completed:
tags: [studio, play-stop, runtime, debugger, shipper, shell]
---
## Objective
Wire the full first-wave `Play/Stop` flow end-to-end through shipper preparation, shared execution session state, native debugger destination, external runtime execution, and direct-stop behavior.
## Background
`DEC-0020`, `DEC-0021`, and `DEC-0022` together now define the intended first-wave behavior. This plan is intentionally last because it integrates the service, session, workspace, and handshake pieces established in the earlier plans.
## Scope
### Included
- `Play` navigation to the debugger destination at flow start.
- Invocation of shipper preparation.
- Propagation of preparation failure into the shared session and debugger destination.
- External runtime spawn `"<runtimePath>" run build` in project root.
- Runtime output publication into shared session and debugger destination.
- Direct runtime kill on `Stop`.
### Excluded
- Preparation cancellation.
- Drift/freshness reuse.
- `debug` command path.
- Profiler behavior.
## Execution Steps
### Step 1 - Wire `Play` into the shared execution destination
**What:** Make pressing `Play` move the user into the debugger destination immediately.
**How:** Navigate to `DebugWorkspace` at the beginning of the flow, before runtime spawn, so preparation failures also appear there.
**File(s):** shell/play controls, workspace selection/navigation logic, `MainView` or equivalent shell coordinator code.
### Step 2 - Invoke shipper preparation and reflect preparation state
**What:** Start the shipper service and reflect `preparing` / `prepare_failed`.
**How:** Transition the shared execution session into `preparing`, consume shipper aggregated preparation output, and stop on first preparation failure.
**File(s):** play orchestration layer, shared session service adapters, shell controls.
### Step 3 - Spawn the external runtime process
**What:** Execute the exact current-wave runtime command.
**How:** Use `ProjectLocalStudioSetup.prometeuRuntimePath` and spawn `"<runtimePath>" run build` with `cwd = project root`. Transition through `connecting`, then `running`, or `runtime_failed` on failure.
**File(s):** runtime orchestration service, shell controls, process-management code.
### Step 4 - Wire `Stop` semantics
**What:** Kill the active runtime process directly.
**How:** Keep one active process handle. Ignore repeated `Play` while active. During `preparing`, `Stop` remains a no-op because cancellation is out of scope.
**File(s):** play/stop controls, runtime orchestration service, shared session service.
### Step 5 - Close the end-to-end loop
**What:** Ensure all logs and state transitions reach the debugger destination consistently.
**How:** Route shipper preparation output plus runtime output into the shared session/log sink. Keep the Activity Feed summary-only.
**File(s):** orchestration layer, shared session adapters, workspace bindings.
## Test Requirements
### Unit Tests
- Verify `Play` transitions the session to `preparing` before runtime spawn.
- Verify repeated `Play` is ignored while runtime is active.
- Verify `Stop` kills the active runtime process and does nothing during `preparing`.
- Verify spawn failures become runtime preflight failures.
### Integration Tests
- End-to-end success path: `Play` opens debugger destination, prepares successfully, spawns runtime, and exposes logs/state.
- Build failure path: debugger destination opens and shows preparation failure without runtime spawn.
- Pack-validation failure path: debugger destination opens and shows preparation failure without runtime spawn.
- Runtime spawn failure path: debugger destination opens and shows runtime failure after successful preparation.
### Manual Verification
- Press `Play` in Studio and confirm the shell navigates to `Debug`.
- Confirm preparation logs appear before runtime output.
- Confirm `Stop` kills a running runtime process.
- Confirm repeated `Play` while running is ignored.
## Acceptance Criteria
- [ ] `Play` opens the debugger destination immediately.
- [ ] The flow executes shipper preparation before runtime spawn.
- [ ] Preparation failures remain visible in the debugger destination.
- [ ] Runtime spawn uses the exact command and working-directory contract from `DEC-0021`.
- [ ] `Stop` kills only the active runtime process and does not cancel preparation.
- [ ] The debugger destination shows merged preparation and runtime logs end-to-end.
## Dependencies
- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
- `PLN-0041` shipper preparation foundation.
- `PLN-0042` shared execution session and log contracts.
- `PLN-0043` first-wave `DebugWorkspace` surface.
- `PLN-0044` runtime handshake selective integration.
## Risks
- End-to-end orchestration may reintroduce ownership confusion if shell, shipper, and debugger boundaries are not kept strict.
- UI timing issues may surface when navigating to the debugger before preparation output begins.
- Process-lifecycle bugs can leave the shell believing a runtime is still active after failure.