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.
- Connect, discover tools, read project context and applicable language/SDK references.
- In DEV, grant control (save all first if prompted). Active Debug prevents granting.
- 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.
- Poll operations by operationId or clientRequestId. Recover a lost start receipt by lookup; never retry frame advancement blindly with a new ID.
- 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 for schemas, authorization, limits and delivery boundaries.
The real headless process adapter and task-service composition can be verified using an extracted runtime distribution:
./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:
./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 and real external-client acceptance are remaining validation boundaries, not confirmed product defects.
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:
./gradlew projects
Run the desktop application:
./gradlew :prometeu-app:run
Run the test suite:
./gradlew test
Generate the aggregated coverage report:
./gradlew jacocoTestReport
Repository Reading Guide
If you are new to the codebase, this order is usually the fastest path:
- Start at
prometeu-appto see application bootstrap. - Read
prometeu-studio-apiandprometeu-studio-corefor Studio contracts and application services. - Read
prometeu-studio-ui-javafxfor the current shell, workspaces, and human-facing flows. - Read
prometeu-appfor Spring composition and provider gateways. - Read
prometeu-packerfor asset and packaging boundaries. - Read
prometeu-compilerwhen you need compiler or PBS language behavior.
Specs And Architecture
Important reference surfaces:
docs/specs/compiler/: shared compiler specificationsdocs/specs/packer/: packer specificationsdocs/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.