prometeu-studio/README.md

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: project VFS, language tooling, compiler pipeline integration, and asset packing. 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: JavaFX application entry point (p.studio.App).
• prometeu-studio: Studio UI, workspaces, project session lifecycle, play/stop flow, and debugger-facing surfaces.
• prometeu-vfs: project document access and save/open contracts.
• prometeu-lsp: language-service integration used by the editor workflow.
• 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
• Code editor
• Debug
• Shipper

At runtime, the app boots an embedded packer, creates a project document VFS, wires LSP services, 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.

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:

1. Start at prometeu-app to see application bootstrap.
2. Read prometeu-studio for the shell, workspaces, and user-facing flows.
3. Read prometeu-vfs, prometeu-lsp, and prometeu-packer for service boundaries.
4. 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.

Discussion Workflow

This repository uses a disciplined discussion workflow under discussion/:

• discussion/workflow/agendas/
• discussion/workflow/decisions/
• discussion/workflow/plans/
• discussion/lessons/
• discussion/index.ndjson

The expected execution flow is:

agenda -> decision -> plan -> implement -> lesson

Do not create new workflow artifacts in legacy docs/**/agendas, docs/**/decisions, docs/**/pull-requests, or docs/**/learn paths.