@jgengine/editor 0.11.0 → 0.13.0

package/dist/mcp/fieldSpec.js

@@ -0,0 +1,174 @@
+// Terse builders so the per-method table below reads as a schema, not a wall of object literals.
+const s = (name, oneOf) => (oneOf === undefined ? { name, kind: "string" } : { name, kind: "string", oneOf });
+const sn = (name) => ({ name, kind: "string", nullable: true });
+const n = (name) => ({ name, kind: "number" });
+const b = (name) => ({ name, kind: "boolean" });
+const sa = (name) => ({ name, kind: "string[]" });
+const o = (name) => ({ name, kind: "object" });
+const oa = (name, of) => (of === undefined ? { name, kind: "object[]" } : { name, kind: "object[]", of });
+const v3 = (name) => ({ name, kind: "vec3" });
+const val = (name) => ({ name, kind: "value" });
+/** Marks a field mandatory for MCP schema generation; presence itself is still checked by `handle`. */
+const req = (spec) => ({ ...spec, required: true });
+const SHAPE = ["circle", "square"];
+const AXES = ["xz", "xy"];
+/**
+ * Per-method field type table — the single source of truth for the RPC boundary. A field listed here
+ * is type-checked when present (see `decodeEditorBridgeRequest`); existence is left to
+ * `EditorHostApi.handle` (whose per-method guards return honest `ok:false` diagnostics for
+ * missing/unknown targets). Type-checking presented fields is what keeps a fuzzed value — a string
+ * where a number belongs, a scalar where an object belongs — from reaching a live session uncoerced.
+ * Unknown extra fields are ignored so a superset payload stays forward-compatible.
+ *
+ * The same table generates the MCP tool `inputSchema`s (see `mcp/tools.ts`), so `required`/`oneOf`/
+ * `of` here also shape what agents are told a tool accepts. The `Record<EditorBridgeRequest["method"],
+ * …>` type is the lockstep guarantee: adding a method to the union in `session.ts` fails to compile
+ * here until it gets a schema, and a stale entry is a compile error too.
+ */
+export const RPC_FIELD_SCHEMAS = {
+    editor_status: [],
+    set_mode: [req(s("mode", ["edit", "walk", "play", "hud"]))],
+    perf_report: [],
+    list_layers: [],
+    list_catalogs: [],
+    get_catalog_entry: [req(s("catalogId")), req(s("entryId"))],
+    set_catalog_entry: [req(s("catalogId")), req(s("entryId")), req(o("patch")), s("label")],
+    add_catalog_entry: [req(s("catalogId")), req(s("entryId")), o("meta"), s("label")],
+    remove_catalog_entry: [req(s("catalogId")), req(s("entryId"))],
+    add_catalog: [req(s("catalogId")), s("label"), o("schema")],
+    remove_catalog: [req(s("catalogId"))],
+    set_catalog_schema: [req(s("catalogId")), req(o("schema")), s("label")],
+    list_selection: [],
+    get_marker: [req(s("id"))],
+    get_volume: [req(s("id"))],
+    set_transform: [req(s("id")), n("x"), n("y"), n("z"), n("rotationY")],
+    set_volume: [req(s("id")), n("radius"), n("height"), n("x"), n("y"), n("z")],
+    set_path: [req(s("id")), s("kind"), n("width"), s("color"), s("label"), o("meta")],
+    set_marker: [req(s("id")), s("kind"), s("color"), s("label"), n("rotationY"), o("meta")],
+    set_note: [req(s("id")), s("text"), o("meta")],
+    set_meta: [req(s("id")), req(o("patch"))],
+    apply_preset: [req(s("id")), req(s("preset"))],
+    select: [req(sa("ids"))],
+    clear_selection: [],
+    camera_goto: [s("id"), n("x"), n("y"), n("z")],
+    camera_frame: [],
+    scene_summary: [],
+    export_document: [],
+    import_document: [req(s("json"))],
+    dispatch: [req(o("command"))],
+    undo: [],
+    redo: [],
+    list_assets: [],
+    place_asset: [req(s("id")), s("kind"), n("x"), n("y"), n("z")],
+    create_terrain: [n("width"), n("depth"), n("cellSize"), n("centerX"), n("centerZ")],
+    sculpt_terrain: [req(s("mode", ["raise", "lower", "smooth", "flatten", "noise", "ramp"])), req(n("x")), req(n("z")), n("radius"), n("strength"), n("target"), n("toX"), n("toZ"), n("seed"), s("shape", SHAPE)],
+    terrain_summary: [],
+    paint_terrain: [req(s("surface")), req(n("x")), req(n("z")), n("radius"), s("shape", SHAPE)],
+    fill_terrain: [req(sn("surface"))],
+    auto_paint: [req(s("surface")), n("minSlope"), n("maxSlope"), n("minHeight"), n("maxHeight")],
+    terrain_materials: [],
+    terrain_layers: [],
+    set_terrain_layers: [req(oa("layers", [req(s("id")), req(s("surface")), n("roughness"), n("tiling"), b("triplanar"), s("tint"), n("opacity")]))],
+    blend_terrain: [req(s("surface")), req(n("x")), req(n("z")), n("radius"), n("strength"), s("shape", SHAPE)],
+    convert_scatter: [req(s("pathId"))],
+    generate_streets: [s("volumeId"), v3("center"), n("halfX"), n("halfZ"), s("seed"), s("mode", ["net", "circuit"]), s("kind"), o("params")],
+    bake_minimap: [n("padding"), n("resolution"), n("waterLevel")],
+    add_foliage: [req(oa("points", [req(n("x")), req(n("z"))])), n("density"), s("item"), s("seed"), n("minSpacing")],
+    scatter_summary: [],
+    set_parent: [req(sa("ids")), req(sn("parentId"))],
+    hierarchy: [],
+    list_prefabs: [],
+    create_prefab: [req(s("id")), req(s("name")), req(sa("ids"))],
+    insert_prefab: [req(s("prefabId")), n("x"), n("y"), n("z")],
+    detach_prefab_instance: [req(s("instanceId"))],
+    delete_prefab: [req(s("prefabId"))],
+    list_collections: [],
+    create_collection: [req(s("id")), req(s("name")), sa("memberIds")],
+    rename_collection: [req(s("id")), req(s("name"))],
+    delete_collection: [req(s("id"))],
+    set_collection_members: [req(s("id")), req(sa("memberIds"))],
+    add_to_collection: [req(s("id")), req(sa("ids"))],
+    remove_from_collection: [req(s("id")), req(sa("ids"))],
+    set_collection_flags: [req(s("id")), s("color"), b("locked"), b("visible")],
+    select_collection: [req(s("id"))],
+    set_object_flags: [req(sa("ids")), b("locked"), b("hidden")],
+    batch_set_properties: [req(sa("ids")), s("color"), s("label"), o("meta")],
+    assign_material: [req(sa("ids")), req(s("materialId"))],
+    list_grids: [],
+    get_grid_cell: [req(s("id")), req(n("col")), req(n("row"))],
+    add_grid_layer: [req(s("id")), req(s("kind")), req(n("cols")), req(n("rows")), s("label"), n("cellSize"), v3("origin"), s("axes", AXES), s("empty"), oa("palette")],
+    remove_grid_layer: [req(s("id"))],
+    set_grid_layer: [req(s("id")), s("label"), s("kind"), b("visible"), s("empty"), n("cellSize"), v3("origin"), s("axes", AXES), oa("palette")],
+    paint_grid_cells: [req(s("id")), req(oa("cells", [req(n("col")), req(n("row")), req(s("value"))]))],
+    fill_grid_rect: [req(s("id")), req(n("col0")), req(n("row0")), req(n("col1")), req(n("row1")), req(s("value"))],
+    flood_fill_grid: [req(s("id")), req(n("col")), req(n("row")), req(s("value"))],
+    resize_grid_layer: [req(s("id")), req(n("cols")), req(n("rows"))],
+    import_grid: [req(s("id")), req(s("kind")), req(s("format", ["ascii", "csv"])), req(s("text")), s("empty"), n("cellSize"), v3("origin"), o("glyphMap"), oa("palette")],
+    push_document_patch: [req(o("patch")), b("force")],
+    pull_document_patches: [n("sinceRevision")],
+    document_revision: [b("includeDocument")],
+    push_runtime_delta: [n("at"), oa("entities"), sa("removeIds"), o("tunables")],
+    pull_runtime_deltas: [n("sinceSeq"), b("includeSnapshot")],
+    runtime_snapshot: [],
+    runtime_summary: [],
+    runtime_get: [req(s("id")), s("path")],
+    runtime_set: [req(s("id")), s("path"), val("value"), o("position"), n("rotationY"), o("values"), b("writeBack")],
+    runtime_pause: [],
+    runtime_resume: [],
+    runtime_step: [n("frames")],
+    set_runtime_override: [req(o("entity"))],
+    clear_runtime_override: [req(s("id"))],
+    write_back_override: [req(s("id"))],
+};
+/** The set of known RPC method names — exported for meta/manifest tooling and tests. @internal */
+export const EDITOR_BRIDGE_METHOD_NAMES = Object.keys(RPC_FIELD_SCHEMAS).sort();
+/** JSON-Schema fragment for one field spec (no `required` — that is aggregated by the object builder). */
+function fieldToJsonSchema(spec) {
+    switch (spec.kind) {
+        case "string":
+            return spec.oneOf !== undefined
+                ? { type: "string", enum: [...spec.oneOf] }
+                : spec.nullable === true
+                    ? { type: ["string", "null"] }
+                    : { type: "string" };
+        case "number":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+        case "string[]":
+            return { type: "array", items: { type: "string" } };
+        case "object":
+            return spec.of !== undefined ? objectSchema(spec.of) : { type: "object" };
+        case "object[]":
+            return { type: "array", items: spec.of !== undefined ? objectSchema(spec.of) : { type: "object" } };
+        case "vec3":
+            return {
+                type: "object",
+                properties: { x: { type: "number" }, y: { type: "number" }, z: { type: "number" } },
+                required: ["x", "y", "z"],
+                additionalProperties: false,
+            };
+        case "value":
+            return {};
+    }
+}
+/** Assembles a closed object schema (properties + required + additionalProperties:false) from field specs. */
+function objectSchema(specs) {
+    const properties = {};
+    const required = [];
+    for (const spec of specs) {
+        properties[spec.name] = fieldToJsonSchema(spec);
+        if (spec.required === true)
+            required.push(spec.name);
+    }
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        additionalProperties: false,
+    };
+}
+/** Generates the MCP tool `inputSchema` for a method from its {@link RPC_FIELD_SCHEMAS} entry. */
+export function buildInputSchema(method) {
+    return objectSchema(RPC_FIELD_SCHEMAS[method]);
+}

package/dist/mcp/rpcRequest.d.ts

@@ -1,4 +1,5 @@
 import type { EditorBridgeRequest } from "../session.js";
+export { EDITOR_BRIDGE_METHOD_NAMES } from "./fieldSpec.js";
 /** One field-level failure surfaced while decoding an untrusted RPC request. */
 export interface RpcRequestDiagnostic {
     path: string;
@@ -13,10 +14,12 @@ export type DecodeRpcRequestResult = {
     errors: RpcRequestDiagnostic[];
 };
 /**
- * Validates an untrusted JSON-decoded RPC payload (from `--rpc` or the HTTP bridge) before it
- * reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method` name.
- * Per-method field shape is still enforced by `handle`'s own dispatch, but a garbled or
- * unknown-method payload is rejected here with a path-specific diagnostic instead of flowing
- * through on a blind cast.
+ * Validates an untrusted JSON-decoded RPC payload (from `--rpc`, the HTTP bridge, or an agent tool
+ * call) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known
+ * `method`, then type-checks every field the method understands against {@link RPC_FIELD_SCHEMAS}.
+ * A garbled method, or a field whose value is the wrong type (a string where a number belongs, a
+ * scalar where an object belongs), is rejected here with a path-specific diagnostic instead of
+ * flowing into a live session on a blind cast. Missing fields and unknown extra fields are left for
+ * `handle` to interpret so the boundary stays forward-compatible.
  */
 export declare function decodeEditorBridgeRequest(raw: unknown): DecodeRpcRequestResult;

package/dist/mcp/rpcRequest.js

@@ -1,107 +1,86 @@
-/** Every `method` an {@link EditorBridgeRequest} may carry — kept in lockstep with the union in `session.ts`. */
-const EDITOR_BRIDGE_METHODS = new Set([
-    "add_foliage",
-    "add_grid_layer",
-    "add_to_collection",
-    "assign_material",
-    "fill_grid_rect",
-    "flood_fill_grid",
-    "get_grid_cell",
-    "import_grid",
-    "list_grids",
-    "paint_grid_cells",
-    "remove_grid_layer",
-    "resize_grid_layer",
-    "set_grid_layer",
-    "auto_paint",
-    "batch_set_properties",
-    "blend_terrain",
-    "camera_frame",
-    "camera_goto",
-    "clear_runtime_override",
-    "clear_selection",
-    "convert_scatter",
-    "create_collection",
-    "create_prefab",
-    "create_terrain",
-    "delete_collection",
-    "delete_prefab",
-    "detach_prefab_instance",
-    "dispatch",
-    "document_revision",
-    "editor_status",
-    "export_document",
-    "fill_terrain",
-    "get_marker",
-    "get_volume",
-    "hierarchy",
-    "import_document",
-    "insert_prefab",
-    "get_catalog_entry",
-    "list_assets",
-    "list_catalogs",
-    "list_collections",
-    "list_layers",
-    "list_prefabs",
-    "list_selection",
-    "paint_terrain",
-    "perf_report",
-    "place_asset",
-    "pull_document_patches",
-    "pull_runtime_deltas",
-    "push_document_patch",
-    "push_runtime_delta",
-    "redo",
-    "remove_from_collection",
-    "rename_collection",
-    "runtime_get",
-    "runtime_pause",
-    "runtime_resume",
-    "runtime_set",
-    "runtime_snapshot",
-    "runtime_step",
-    "runtime_summary",
-    "scatter_summary",
-    "scene_summary",
-    "sculpt_terrain",
-    "select",
-    "select_collection",
-    "set_catalog_entry",
-    "set_collection_flags",
-    "set_collection_members",
-    "set_marker",
-    "set_meta",
-    "set_mode",
-    "set_note",
-    "set_parent",
-    "set_path",
-    "set_runtime_override",
-    "set_terrain_layers",
-    "set_transform",
-    "set_volume",
-    "terrain_layers",
-    "terrain_materials",
-    "terrain_summary",
-    "undo",
-    "write_back_override",
-]);
+import { RPC_FIELD_SCHEMAS } from "./fieldSpec.js";
+export { EDITOR_BRIDGE_METHOD_NAMES } from "./fieldSpec.js";
+/** Every `method` an {@link EditorBridgeRequest} may carry, derived from the schema table's keys. */
+const EDITOR_BRIDGE_METHODS = new Set(Object.keys(RPC_FIELD_SCHEMAS));
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isVec3(value) {
+    return isPlainObject(value) && typeof value.x === "number" && typeof value.y === "number" && typeof value.z === "number";
+}
+function validateField(value, spec, errors) {
+    if (value === undefined)
+        return; // presence is enforced by handle's per-method guards, not here
+    const path = `$.${spec.name}`;
+    if (value === null) {
+        if (spec.nullable !== true)
+            errors.push({ path, message: `expected a ${spec.kind}` });
+        return;
+    }
+    switch (spec.kind) {
+        case "string":
+            if (typeof value !== "string")
+                errors.push({ path, message: "expected a string" });
+            else if (spec.oneOf !== undefined && !spec.oneOf.includes(value)) {
+                errors.push({ path, message: `expected one of ${spec.oneOf.join(" | ")}` });
+            }
+            return;
+        case "number":
+            if (typeof value !== "number" || Number.isNaN(value))
+                errors.push({ path, message: "expected a number" });
+            return;
+        case "boolean":
+            if (typeof value !== "boolean")
+                errors.push({ path, message: "expected a boolean" });
+            return;
+        case "string[]":
+            if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+                errors.push({ path, message: "expected an array of strings" });
+            }
+            return;
+        case "object":
+            if (!isPlainObject(value))
+                errors.push({ path, message: "expected an object" });
+            return;
+        case "object[]":
+            if (!Array.isArray(value) || value.some((entry) => !isPlainObject(entry))) {
+                errors.push({ path, message: "expected an array of objects" });
+            }
+            return;
+        case "vec3":
+            if (!isVec3(value))
+                errors.push({ path, message: "expected {x,y,z} numbers" });
+            return;
+        case "value":
+            return;
+    }
+}
 /**
- * Validates an untrusted JSON-decoded RPC payload (from `--rpc` or the HTTP bridge) before it
- * reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method` name.
- * Per-method field shape is still enforced by `handle`'s own dispatch, but a garbled or
- * unknown-method payload is rejected here with a path-specific diagnostic instead of flowing
- * through on a blind cast.
+ * Validates an untrusted JSON-decoded RPC payload (from `--rpc`, the HTTP bridge, or an agent tool
+ * call) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known
+ * `method`, then type-checks every field the method understands against {@link RPC_FIELD_SCHEMAS}.
+ * A garbled method, or a field whose value is the wrong type (a string where a number belongs, a
+ * scalar where an object belongs), is rejected here with a path-specific diagnostic instead of
+ * flowing into a live session on a blind cast. Missing fields and unknown extra fields are left for
+ * `handle` to interpret so the boundary stays forward-compatible.
  */
 export function decodeEditorBridgeRequest(raw) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
         return { ok: false, errors: [{ path: "$", message: "expected an RPC request object" }] };
     }
-    const method = raw.method;
+    const record = raw;
+    const method = record.method;
     if (typeof method !== "string") {
         return { ok: false, errors: [{ path: "$.method", message: "expected a string" }] };
     }
     if (!EDITOR_BRIDGE_METHODS.has(method)) {
         return { ok: false, errors: [{ path: "$.method", message: `unknown method "${method}"` }] };
     }
+    const errors = [];
+    for (const spec of RPC_FIELD_SCHEMAS[method]) {
+        validateField(record[spec.name], spec, errors);
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
     return { ok: true, request: raw };
 }