docs(studio): keep README focused on project onboarding
This commit is contained in:
@@ -0,0 +1,213 @@
|
||||
# Studio Development Guide
|
||||
|
||||
Run commands from the Studio repository root unless stated otherwise.
|
||||
This guide covers installation, native runtime qualification, external tooling
|
||||
and opt-in integration checks. See the [project README](../README.md) for the
|
||||
application overview and basic build commands.
|
||||
|
||||
## Native Runtime Installation and Qualification
|
||||
|
||||
Build the native umbrella distribution with `../runtime/scripts/local-dist.sh`.
|
||||
It packages `prometeu`, `prometeu-runtime` (desktop/Studio Play) and
|
||||
`prometeu-headless` (deterministic automation). Select the extracted
|
||||
`../runtime/dist-staging/stable/prometeu-cli-<target>` directory in Studio.
|
||||
An unchanged dispatcher can belong to several releases: Studio selects a profile
|
||||
only when all three executable hashes match the same qualified bundle.
|
||||
|
||||
After changing a native binary, qualify the actual installation before building
|
||||
or launching Studio with its updated catalog:
|
||||
|
||||
```sh
|
||||
make -C ../tooling venv
|
||||
../tooling/.venv/bin/python ../tooling/scripts/qualify.py \
|
||||
--studio . \
|
||||
--runtime ../runtime/dist-staging/stable/prometeu-cli-aarch64-apple-darwin
|
||||
```
|
||||
|
||||
This command executes the native glyph/scene 16/17 boundary test afresh, verifies
|
||||
the evidence and executable identities, then publishes an exact capacity profile
|
||||
under `prometeu-app/src/main/resources/asset-capacity`. Review/include those
|
||||
resources when distributing Studio. It neither builds a replacement runtime nor
|
||||
relaxes the execution guard. A failed qualification publishes no catalog entry.
|
||||
The native build stays independent of the JVM; qualification is an explicit
|
||||
consumer verification step, separate from pressing Play.
|
||||
|
||||
## Installation and IntelliJ Development
|
||||
|
||||
Build and stage the complete distribution, including its Java runtime:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:stageStudioInstallation
|
||||
```
|
||||
|
||||
The macOS default is `~/Library/Application Support/Prometeu/Studio/current`.
|
||||
Staging validates a new version before atomically changing `current`, retaining
|
||||
older versions for rollback and running processes. Native client registration
|
||||
uses absolute paths and argument arrays, independent of shell PATH:
|
||||
|
||||
```text
|
||||
command: <installation>/current/runtime/bin/java
|
||||
args: ["-cp", "<installation>/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", "<absolute-project-root>"]
|
||||
```
|
||||
|
||||
For development, use an isolated installation:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:stageStudioInstallation -PstudioInstallationRoot=/absolute/dev-installation
|
||||
```
|
||||
|
||||
In IntelliJ, run/debug `p.studio.app.StudioLauncher` with the `prometeu-app`
|
||||
runtime classpath and VM option `-Dstudio.installationRoot=/absolute/dev-installation`.
|
||||
The desktop and client-owned connector are separate JVMs. To debug the latter,
|
||||
add the development-only VM argument
|
||||
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005`
|
||||
before `-cp` in the local MCP entry, restart that MCP process, then use IntelliJ's
|
||||
**Remote JVM Debug** on localhost:5005. Do not commit this local configuration.
|
||||
Because manual edits to the managed entry are protected, restore its original
|
||||
content before using preparation again. Regular registration never enables JDWP.
|
||||
|
||||
## External Coding Agents (MCP)
|
||||
|
||||
The following authorization workflow belongs to the previous DEV adapter. The new
|
||||
Play UI does not yet expose a grant/configuration surface. Headless protocol,
|
||||
task authority, MCP tool schemas and the installed stdio connector retain their
|
||||
existing entry points.
|
||||
|
||||
Studio includes its own `mcp --project <absolute-root>` mode. Configure the native
|
||||
client once; project grants and desktop restarts no longer require copying ports
|
||||
or tokens. The initial integration targets Codex on macOS.
|
||||
|
||||
1. Install/stage Studio with its bundled Java runtime (see installation above).
|
||||
New projects prepare the local client entry during scaffolding. Opening an existing project
|
||||
also prepares its enabled integration automatically; Studio starts the shared
|
||||
MCP server itself. **DEV → Prepare assistant** retries preparation after resolving
|
||||
a reported setup conflict. Opening a project does not grant agent control.
|
||||
2. Open the coding client in the project directory. Trust the project and reload
|
||||
MCP once if the client requests it. Studio does not alter client approval policy.
|
||||
Tools can initialize/list even before the desktop is open or access is granted.
|
||||
3. Open the project in Studio and grant control in DEV (save first if prompted).
|
||||
Active Debug prevents granting. The connector discovers access automatically.
|
||||
4. The agent acquires a task, consults project/language/SDK references, edits saved
|
||||
project files with its native tools and validates through LSP/build. SDK and
|
||||
external libraries remain read-only.
|
||||
5. Recover uncertain operations by operationId/clientRequestId lookup within the
|
||||
same task; never replay build/advance blindly. Explicitly release control when
|
||||
done. Human reclaim also revokes access; stop direct external file edits separately.
|
||||
|
||||
The client invokes the same Studio artifact over stdio. It forwards to Studio's
|
||||
project-scoped loopback service using protected, transient
|
||||
`.studio/mcp/connection.json`. The permanent `.codex/config.toml` entry contains
|
||||
installed Java/classpath/root arguments, not credentials. Both local outputs are
|
||||
ignored by Git. Unrelated client settings are preserved; tracked or conflicting
|
||||
Studio entries require deliberate resolution. `.studio/setup.json` preserves
|
||||
neutral integration intent and existing runtime/editor settings.
|
||||
|
||||
After desktop restart, grant again in DEV. Keep the same client session and
|
||||
configuration; old task identities and operation receipts are not restored.
|
||||
DEV displays connection separately from project authority. No project-local
|
||||
launcher, Python transport script or embedded chat is required.
|
||||
|
||||
### Reading external source code
|
||||
|
||||
VS Code F12 opens SDK/core and admitted libraries as read-only documents, with
|
||||
hover, continued F12 and syntax highlighting. SDK/core stay bundled; no editorial
|
||||
copies are created. After a source revision changes or a session ends, navigate
|
||||
again instead of reusing old positions.
|
||||
|
||||
For MCP, use `studio_language_query` with `operation: "definition"`, then pass a
|
||||
returned `prometeu-source:` URI to `operation: "readExternalSource"`. The response
|
||||
contains `descriptor` and `text`; hover and definition accept the same URI within
|
||||
the owning task. Another task cannot reuse it. MCP does not require VS Code open.
|
||||
External or mixed edit proposals are refused in full. Library installation/cache
|
||||
management is outside this feature. See the [extension guide](../tools/vscode-extension/README.md).
|
||||
|
||||
The production tools cover context, references, task control, LSP,
|
||||
build/pack, operation lookup/cancellation and headless execution.
|
||||
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](specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md)
|
||||
for schemas, authorization, limits and delivery boundaries.
|
||||
|
||||
### Troubleshooting automation
|
||||
|
||||
| Symptom | Action |
|
||||
| --- | --- |
|
||||
| Waiting for access / desktop restarted | Open the project and grant again in DEV. Keep the existing client configuration. |
|
||||
| Stale connection / incompatible catalog | Grant fresh access, or update the installed Studio when versions differ. Do not edit transient credentials. |
|
||||
| Preparation conflict | Preserve the existing client settings; resolve a tracked/user-owned/edited Studio table explicitly, then prepare again. |
|
||||
| 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.
|
||||
|
||||
## Integration Checks
|
||||
|
||||
Unit tests run through `./gradlew test`. Process, network, desktop and actual
|
||||
application/provider composition checks use separate integration tasks, including
|
||||
fixture subprocesses. These suites remain in Studio; `../tooling` prepares their
|
||||
environment and orchestrates selected commands.
|
||||
Integration checks are excluded from the runtime and Studio pipelines.
|
||||
|
||||
### Installed Studio Connector
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:installedConnectorTest
|
||||
```
|
||||
|
||||
Checks bundled Java, upgrade/rollback, project paths with spaces, minimal
|
||||
environment, scaffolding/preparation and JavaFX startup.
|
||||
|
||||
### Integrated Play
|
||||
|
||||
Requires a desktop environment and an installed native runtime:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:studioPlayProcessTest -PstudioRuntimeInstall=/absolute/runtime-install
|
||||
./gradlew :prometeu-app:studioPlayDesktopTest -PstudioRuntimeInstall=/absolute/runtime-install
|
||||
```
|
||||
|
||||
Add `-PstudioPlayStress=true` for the 30-second presentation/FX-delay/20-cycle
|
||||
check. Fixtures use a disposable copy of `test-projects/pong`. No external port
|
||||
checkout is required. Changed native executables require renewed qualification
|
||||
as described above.
|
||||
|
||||
### Headless Runtime and Application Composition
|
||||
|
||||
Use an extracted runtime distribution:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime
|
||||
```
|
||||
|
||||
Exercises the real runtime, installed PBS examples, canonical PNGs, reset/reboot,
|
||||
cancellation and process cleanup, plus saved-file LSP/build corrective loops.
|
||||
The task requires the supplied runtime installation.
|
||||
|
||||
### MCP and DEV Desktop Integration
|
||||
|
||||
This check exercises the retained DEV adapter. It requires a POSIX desktop and
|
||||
free port 7777:
|
||||
|
||||
```bash
|
||||
./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2
|
||||
```
|
||||
|
||||
The HTTP client drives LSP, build and a fixed input timeline; output and visible
|
||||
DEV pixels are compared with a separate direct-JSONL runtime process. Scenarios
|
||||
include reset, cancellation, disconnect/reconnect, revocation, project/app closure,
|
||||
crash, forced shutdown and return to manual Debug. Only test-owned processes are
|
||||
terminated or suspended. After a forced-shutdown error, a second explicit reclaim
|
||||
can acknowledge completed cleanup; control stays locked until cleanup is confirmed.
|
||||
|
||||
These commands describe available checks. Record actual runs, environment,
|
||||
results, acceptance evidence and pending investigations in the owning AIE Work.
|
||||
@@ -140,7 +140,7 @@ umbrella distribution produced by `runtime/scripts/local-dist.sh`, including rea
|
||||
Pong Play and the deterministic headless process. Capacity qualification identifies
|
||||
the dispatcher and both native backends as one exact bundle; multiple releases may
|
||||
share an unchanged dispatcher. The explicit qualification command is documented in
|
||||
the [Studio README](../../../README.md).
|
||||
the [development guide](../../development.md#native-runtime-installation-and-qualification).
|
||||
|
||||
Earlier presentation performance measurements used debug native binaries.
|
||||
Windows/Linux, release performance, physical HiDPI pixel alignment, and human
|
||||
|
||||
Reference in New Issue
Block a user