dev/prometeuc-improvements (#5)

Co-authored-by: Nilton Constantino <nilton.constantino@visma.com>
Reviewed-on: #5
This commit was merged in pull request #5.
This commit is contained in:
2026-01-21 10:55:47 +00:00
co-authored by Nilton Constantino
parent 73353d864d
commit 0e6da1433b
76 changed files with 2820 additions and 756 deletions
+83
View File
@@ -0,0 +1,83 @@
# Prometeu DevTools Protocol
This document describes the communication protocol between the Prometeu Runtime and development tools (such as the Prometeu Debugger).
## Overview
The protocol is based on JSON, sent via a transport connection (usually TCP). Each message is a JSON object on a single line (JSONL).
## Structure
- **[protocol.json](protocol.json)**: Formal definition of the protocol in JSON format.
- **[protocol.md](README.md)**: Human-readable documentation describing commands, events, and types.
- **[examples/](examples)**: Examples of message flows (handshake, breakpoints, etc.) in JSONL format.
## Versioning
The protocol has an explicit version defined in the `protocol_version` field.
- Incompatible changes (breaking changes) increment the major version.
- New fields in existing messages should be optional whenever possible to maintain backward compatibility.
The current protocol version is: **1**
## Handshake
Upon connecting, the Runtime sends a handshake message to the client.
### Runtime -> Client
```json
{
"type": "handshake",
"protocol_version": 1,
"runtime_version": "0.1.0",
"cartridge": {
"app_id": 1,
"title": "ColorSquare",
"app_version": "1.0.0",
"app_mode": "Debug"
}
}
```
### Client -> Runtime
The client must respond with `start` or `ok` to start the session.
```json
{ "type": "start" }
```
## Requests
The client can send the following requests to control execution:
| Name | Parameters | Description |
|------|------------|-----------|
| `pause` | `[]` | Pauses VM execution. |
| `resume` | `[]` | Resumes VM execution. |
| `step` | `[]` | Executes a single instruction (PC). |
| `stepFrame` | `[]` | Executes until the next frame. |
| `getState` | `[]` | Returns the current VM state (`pc`, `stack_top`, `frame_index`, `app_id`). |
| `setBreakpoint` | `{"pc": number}` | Sets a breakpoint at the specified address. |
| `clearBreakpoint` | `{"pc": number}` | Removes a breakpoint at the specified address. |
## Responses
Some requests generate specific responses. For example, `getState` returns the VM state.
## Events
The Runtime can send asynchronous events to the client:
| Name | Fields | Description |
|------|--------|-----------|
| `breakpointHit` | `pc`, `frame_index` | Emitted when execution hits a breakpoint. |
| `log` | `level`, `source`, `msg` | Emitted when the running code generates a log. |
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Execution statistics sent periodically. |
| `cert` | `rule`, `used`, `limit`, `frame_index` | Certification information and resource limits. |
## Examples
See the `examples/` folder for complete message flows.
@@ -0,0 +1,4 @@
{"type":"start"}
{"type":"pause"}
{"type":"getState"}
{"type":"resume"}
@@ -0,0 +1,2 @@
{"type":"setBreakpoint","pc":120}
{"event":"breakpointHit","pc":120,"frame_index":10}
@@ -0,0 +1,2 @@
{"type":"handshake","protocol_version":1,"runtime_version":"0.1","cartridge":{"app_id":1,"title":"ColorSquare","app_version":"1.0.0","app_mode":"Debug"}}
{"type":"start"}
+61
View File
@@ -0,0 +1,61 @@
{
"protocol_version": 1,
"handshake": {
"runtime_to_client": {
"type": "handshake",
"fields": ["protocol_version", "runtime_version", "cartridge"]
},
"client_to_runtime": {
"type": "start|ok"
}
},
"requests": [
{
"type": "pause",
"params": []
},
{
"type": "resume",
"params": []
},
{
"type": "step",
"params": []
},
{
"type": "stepFrame",
"params": []
},
{
"type": "getState",
"params": [],
"response": ["pc", "stack_top", "frame_index", "app_id"]
},
{
"type": "setBreakpoint",
"params": ["pc"]
},
{
"type": "clearBreakpoint",
"params": ["pc"]
}
],
"events": [
{
"event": "breakpointHit",
"fields": ["pc", "frame_index"]
},
{
"event": "log",
"fields": ["level", "source", "msg"]
},
{
"event": "telemetry",
"fields": ["frame_index", "vm_steps", "syscalls", "cycles"]
},
{
"event": "cert",
"fields": ["rule", "used", "limit", "frame_index"]
}
]
}
+6
View File
@@ -0,0 +1,6 @@
{
"name": "@prometeu/sdk",
"version": "0.1.0",
"main": "src/index.ts",
"types": "types/index.d.ts"
}
+2
View File
@@ -0,0 +1,2 @@
export const Audio = audio;
export type Audio = Prometeu.Audio;
+25
View File
@@ -0,0 +1,25 @@
export type Color565 = Prometeu.Color565;
function clamp8(n: number): number {
return n < 0 ? 0 : n > 255 ? 255 : n | 0;
}
export const Color: Prometeu.Color = {
black: 0x0000 as Color565,
white: 0xffff as Color565,
red: 0xf800 as Color565,
green: 0x07e0 as Color565,
blue: 0x001f as Color565,
yellow: 0xffe0 as Color565,
cyan: 0x07ff as Color565,
magenta: 0xf81f as Color565,
indigo: 0x4810 as Color565,
rgb(r: number, g: number, b: number): Color565 {
r = clamp8(r); g = clamp8(g); b = clamp8(b);
const r5 = (r >> 3) & 0x1f;
const g6 = (g >> 2) & 0x3f;
const b5 = (b >> 3) & 0x1f;
return ((r5 << 11) | (g6 << 5) | b5) as Color565;
},
};
+2
View File
@@ -0,0 +1,2 @@
export const Fs = fs;
export type Fs = Prometeu.Fs;
+1
View File
@@ -0,0 +1 @@
export type Gfx = Prometeu.Gfx;
+8
View File
@@ -0,0 +1,8 @@
export { Color } from "./color";
export { Pad, Touch } from "./input";
export { Gfx } from "./gfx";
export { System } from "./system";
export { Audio } from "./audio";
export { Fs } from "./fs";
export { Log, LogLevel } from "./log";
export type { Color565 } from "./color";
+4
View File
@@ -0,0 +1,4 @@
export const Pad: Prometeu.Pad = pad;
export const Touch: Prometeu.Touch = touch;
+11
View File
@@ -0,0 +1,11 @@
export const Log = log;
export type Log = Prometeu.Log;
export enum LogLevel {
Trace = 0,
Debug = 1,
Info = 2,
Warn = 3,
Error = 4,
Fatal = 5,
}
+2
View File
@@ -0,0 +1,2 @@
export const System = system;
export type System = Prometeu.System;
+4
View File
@@ -0,0 +1,4 @@
{
"compilerOptions": {
}
}
+95
View File
@@ -0,0 +1,95 @@
export {}; // that is a module, should not include any other scope here
declare global {
namespace Prometeu {
type Color565 = number & { readonly __brand: "Color565" };
interface Button {
readonly down: boolean;
readonly pressed: boolean;
readonly released: boolean;
readonly holdFrames: number;
}
interface Pad {
readonly up: Button;
readonly down: Button;
readonly left: Button;
readonly right: Button;
readonly a: Button;
readonly b: Button;
readonly x: Button;
readonly y: Button;
readonly l: Button;
readonly r: Button;
readonly start: Button;
readonly select: Button;
}
interface Touch {
readonly x: number;
readonly y: number;
readonly button: Button;
}
interface Gfx {
fillRect(x: number, y: number, w: number, h: number, color: Color565): void;
drawLine(x1: number, y1: number, x2: number, y2: number, color: Color565): void;
drawCircle(x: number, y: number, r: number, color: Color565): void;
drawDisc(x: number, y: number, r: number, borderColor: Color565, fillColor: Color565): void;
drawSquare(x: number, y: number, w: number, h: number, borderColor: Color565, fillColor: Color565): void;
clear(color: Color565): void;
}
interface Color {
readonly black: Color565;
readonly white: Color565;
readonly red: Color565;
readonly green: Color565;
readonly blue: Color565;
readonly yellow: Color565;
readonly cyan: Color565;
readonly magenta: Color565;
readonly indigo: Color565;
readonly color_key: Color565;
readonly orange: Color565;
readonly gray: Color565;
readonly grey: Color565;
rgb(r: number, g: number, b: number): Color565;
}
interface System {
hasCart(): boolean;
}
interface Audio {
playSample(sampleId: number, voiceId: number, volume: number, pan: number, pitch: number): void;
}
interface Fs {
open(path: string): number;
read(handle: number): string | null;
write(handle: number, content: string): boolean;
close(handle: number): void;
listDir(path: string): string | null;
exists(path: string): boolean;
delete(path: string): boolean;
}
interface Log {
write(level: number, msg: string): void;
writeTag(level: number, tag: number, msg: string): void;
}
}
export const pad: Prometeu.Pad;
export const touch: Prometeu.Touch;
export const gfx: Prometeu.Gfx;
export const audio: Prometeu.Audio;
export const fs: Prometeu.Fs;
export const log: Prometeu.Log;
export const color: Prometeu.Color;
export const system: Prometeu.System;
}