194 lines
9.9 KiB
Markdown
194 lines
9.9 KiB
Markdown
# Prometeu Studio
|
|
|
|
Prometeu Studio is the desktop development environment for the Prometeu toolchain.
|
|
|
|
This repository packages the Studio shell together with the embedded services it depends on: compiler pipeline integration, asset packing, runtime/debug orchestration, and project-local Studio state. The current implementation is a Java/JavaFX multi-module Gradle build.
|
|
|
|
## What Lives Here
|
|
|
|
The root project is a monorepo with these main areas:
|
|
|
|
- `prometeu-app`: Spring Boot non-web composition, concrete adapters, packaging, and JavaFX entry point (`p.studio.app.StudioLauncher`).
|
|
- `prometeu-studio-api`: toolkit-neutral Studio contracts and operation surfaces.
|
|
- `prometeu-studio-core`: JavaFX-free project, session, assets, shipper, runtime, and execution services.
|
|
- `prometeu-studio-ui-javafx`: the current human-facing JavaFX adapter.
|
|
- `prometeu-packer`: embedded packer APIs and implementation used by Studio.
|
|
- `prometeu-compiler`: compiler core, build pipeline, frontend APIs, and the PBS frontend.
|
|
- `prometeu-infra`: shared infrastructure used across modules.
|
|
- `docs/`: normative specifications and architectural references.
|
|
- `discussion/`: workflow artifacts for agendas, decisions, plans, and lessons.
|
|
- `test-projects/`: sample workspaces used for local development and tests.
|
|
|
|
## Current Product Shape
|
|
|
|
The Studio shell currently organizes the product around four workspaces:
|
|
|
|
- Assets
|
|
- Debug
|
|
- DEV (external-agent authorization and observation)
|
|
- Shipper
|
|
|
|
At runtime, the app boots an embedded packer, restores project-local Studio state, and opens the Studio launcher window. Project creation currently scaffolds a Prometeu workspace with `prometeu.json`, `src/`, `assets/`, `build/`, `cartridge/`, `.workspace/`, and local Studio metadata.
|
|
|
|
## External Coding Agents (MCP)
|
|
|
|
Open a project and select **DEV → Copy MCP configuration**. The copied JSON is a
|
|
provider-neutral connection descriptor: use its `url` and `headers.Authorization`
|
|
in your external client's Streamable HTTP MCP setup, and provide its `projectRoot`
|
|
and instructions to the agent. Adapt the configuration syntax to your client;
|
|
there is no embedded chat or provider-specific setup wizard.
|
|
|
|
Keep the descriptor/token private and out of versioned files and logs. The endpoint
|
|
is local to this computer. After restarting Studio, copy it again and update the
|
|
client: both the port and token are ephemeral. Copying or connecting does not
|
|
authorize edits or start a task.
|
|
|
|
1. Connect, discover tools, read project context and applicable language/SDK references.
|
|
2. In DEV, grant control (save all first if prompted). Active Debug prevents granting.
|
|
3. The agent acquires a task, edits saved project files using its own tools, and
|
|
validates through LSP/build. SDK and external libraries are consultable, read-only.
|
|
4. Poll operations by operationId or clientRequestId. Recover a lost start receipt
|
|
by lookup; never retry frame advancement blindly with a new ID.
|
|
5. The agent explicitly releases control. To interrupt, use DEV's reclaim button
|
|
and stop the external client separately: Studio cannot prevent its direct file writes.
|
|
|
|
The current production tools cover context, references, task control, LSP,
|
|
build/pack, operation lookup/cancellation and headless execution (17 tools).
|
|
Headless requires a runtime installation configured for the project; missing or
|
|
incompatible installations fail explicitly. DEV is an
|
|
observation panel, not manual Play/input for the agent's session; **Debug** retains
|
|
the human testing workflow. Edits are preserved on cancellation; Git/review/recovery
|
|
remain the developer's responsibility.
|
|
|
|
See the [MCP contract](docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md)
|
|
for schemas, authorization, limits and delivery boundaries.
|
|
|
|
### Troubleshooting automation
|
|
|
|
| Symptom | Action |
|
|
| --- | --- |
|
|
| Connection rejected after Studio restarts | Copy DEV's configuration again: the token and OS-assigned endpoint are session-local. Do not publish the token. |
|
|
| Acquisition rejected or project busy | Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls. |
|
|
| `RUNTIME_UNAVAILABLE` or handshake incompatibility | Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute. |
|
|
| `NO_FRAME_AVAILABLE` | Advance at least one frame before requesting a capture. |
|
|
| Advance/page limit rejected | Respect advertised limits and use reference pagination. Runtime's default maximum is 600 frames per advance; requests are not silently clamped. |
|
|
| Unknown language or missing reference | Inspect project context and the declared manifest language; use only advertised capabilities/reference IDs. PBS is a creation default, not an unknown-language fallback. |
|
|
| Returning control reports cleanup failure | Stop the external client's direct editing separately, then retry DEV reclaim after owned-process cleanup. Do not bypass the lock or restore stale editor buffers. |
|
|
|
|
Language and SDK references are bundled locally; reading them does not require a
|
|
compiler checkout or network download. SDK/external-library changes remain outside
|
|
the game-authoring task, even when a reference exposes a limitation.
|
|
|
|
The real headless process adapter and task-service composition can be verified
|
|
using an extracted runtime distribution:
|
|
|
|
```bash
|
|
./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime
|
|
```
|
|
|
|
This gate builds an installed PBS example, launches the actual runtime, checks
|
|
canonical PNGs and explicit reset/reboot, cancels an advance and verifies process
|
|
cleanup. It also runs the actual app composition through saved-file LSP queries,
|
|
rebuilds and corrective loops after compile errors and guest faults. It does not
|
|
download a runtime or substitute a protocol fixture.
|
|
|
|
To verify the complete HTTP-to-runtime-to-DEV image path, run this separate gate
|
|
in a desktop environment:
|
|
|
|
```bash
|
|
./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2
|
|
```
|
|
|
|
It opens the real DEV view, grants control, uses an HTTP MCP client to query LSP,
|
|
edit/build the installed PBS example and execute a fixed input timeline. PNG bytes,
|
|
frame identities, state and fault are compared with a separate direct-JSONL runtime
|
|
process; every decoded ImageView pixel and its visible identity/stale label are
|
|
checked. Reset, fresh-session repetition and rebuild are included. This automated
|
|
client is not the external coding-agent acceptance gate.
|
|
|
|
The same suite also exercises cancellation, disconnect/reconnect, revocation,
|
|
project/app closure, crash and forced shutdown, corrective builds, and return to
|
|
the real manual Debug host. These scenarios require a POSIX desktop (validated
|
|
on macOS ARM64) and free port 7777. Only processes created by the test are killed
|
|
or suspended. After a forced-shutdown error, an explicit second reclaim can
|
|
acknowledge completed cleanup; control stays locked until cleanup is confirmed.
|
|
|
|
### Follow-ups after the AI-first implementation
|
|
|
|
The following findings are recorded for investigation after implementation; they
|
|
are not considered fixed by the passing integration tests:
|
|
|
|
- **PBS/LSP SDK navigation:** definition lookup for the bundled SDK's `Input.pad()`
|
|
currently returns no location. Project-source navigation and indexed SDK reference
|
|
reads work. Investigate SDK symbol resolution separately; an empty definition
|
|
result is not evidence of missing runtime support or permission to edit the SDK.
|
|
- **Build tooling:** the validation environment's JDK 25 triggers Kotlin's target-24
|
|
fallback and Java/Kotlin target compatibility warnings in `buildSrc`. The targeted
|
|
regression passes, but the toolchain/target alignment needs separate review.
|
|
|
|
Cross-platform desktop coverage remains a validation boundary, not a confirmed
|
|
product defect. Desktop acceptance so far covers macOS ARM64 and Codex CLI only.
|
|
|
|
The first real Codex CLI acceptance run exercised editing, LSP, build/pack, input,
|
|
1,110 frames, native MCP images and explicit release. The developer confirmed the
|
|
DEV result and successfully ran the edited game using manual Debug Play afterward.
|
|
Additional follow-ups from that run: clearer errors for oversized
|
|
reference pages, guidance for sequential headless queries after `BUSY`, and easier
|
|
discovery of framebuffer dimensions. Capture before the first completed frame
|
|
correctly returns `NO_FRAME_AVAILABLE`; it is not a runtime defect. Noninteractive
|
|
clients must also provide an approval path for MCP work calls; the acceptance used
|
|
Codex's approval review with a project-scoped workspace-write sandbox.
|
|
|
|
## Requirements
|
|
|
|
- JDK 21 or newer recommended for local development
|
|
- Gradle wrapper (`./gradlew`) included in the repository
|
|
- A desktop environment capable of running JavaFX
|
|
|
|
## Common Commands
|
|
|
|
Run the full project graph listing:
|
|
|
|
```bash
|
|
./gradlew projects
|
|
```
|
|
|
|
Run the desktop application:
|
|
|
|
```bash
|
|
./gradlew :prometeu-app:run
|
|
```
|
|
|
|
Run the test suite:
|
|
|
|
```bash
|
|
./gradlew test
|
|
```
|
|
|
|
Generate the aggregated coverage report:
|
|
|
|
```bash
|
|
./gradlew jacocoTestReport
|
|
```
|
|
|
|
## Repository Reading Guide
|
|
|
|
If you are new to the codebase, this order is usually the fastest path:
|
|
|
|
1. Start at `prometeu-app` to see application bootstrap.
|
|
2. Read `prometeu-studio-api` and `prometeu-studio-core` for Studio contracts and application services.
|
|
3. Read `prometeu-studio-ui-javafx` for the current shell, workspaces, and human-facing flows.
|
|
4. Read `prometeu-app` for Spring composition and provider gateways.
|
|
5. Read `prometeu-packer` for asset and packaging boundaries.
|
|
6. Read `prometeu-compiler` when you need compiler or PBS language behavior.
|
|
|
|
## Specs And Architecture
|
|
|
|
Important reference surfaces:
|
|
|
|
- `docs/specs/compiler/`: shared compiler specifications
|
|
- `docs/specs/packer/`: packer specifications
|
|
- `docs/vm-arch/`: VM and ISA architecture references
|
|
|
|
These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.
|