# 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. 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. Full HTTP/visual integration and external-agent acceptance remain subsequent integration gates. ## 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.