housekeep
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user