Update doc + improve security (remove julia code evaluation from remotes by default)

Author: VEZY

.github/workflows/CI.yml

@@ -111,6 +111,12 @@ jobs:
       - name: Build graph editor frontend
         working-directory: frontend
         run: npm run build
+      - name: Check committed graph editor assets
+        run: |
+          git diff --exit-code -- frontend/dist || {
+            echo "frontend/dist is stale. Run npm run build in frontend/ and commit the rebuilt assets.";
+            exit 1;
+          }
       - name: Install Playwright browser
         working-directory: frontend
         run: npx playwright install --with-deps chromium

docs/src/step_by_step/graph_visualization_editor.md

@@ -31,7 +31,7 @@ The thermal time model computes `TT_cu`, the LAI model consumes `TT_cu` and comp
 
 ```@raw html
 <iframe
-  src="../www/simple_dependency_graph.html"
+  src="../../www/simple_dependency_graph.html"
   style="width: 100%; height: 720px; border: 1px solid #d8cfc2; border-radius: 8px; background: #f7f0e7;"
   title="PlantSimEngine dependency graph example"
 ></iframe>
@@ -54,44 +54,18 @@ write_graph_view("dependency_graph.html", mapping)
 
 The returned file path is absolute, so you can print it, open it in a browser, or embed it in another documentation site.
 
-## Embedding a graph in package documentation
-
-For package documentation built with Documenter, generate the HTML file before `makedocs` and place it somewhere under `docs/src`, for example `docs/src/www/model_graph.html`:
-
-```julia
-# docs/make.jl
-using Documenter
-using PlantSimEngine
-using YourPackage
-
-mapping = YourPackage.default_mapping()
-write_graph_view(joinpath(@__DIR__, "src", "www", "model_graph.html"), mapping)
+## Interactive editor
 
-makedocs(;
-    # ...
-)
-```
+The interactive editor uses the same graph JSON as the static viewer, but it keeps a WebSocket connection open to Julia. Julia remains the source of truth: the browser sends edit commands, Julia applies them to the [`ModelMapping`](@ref), recompiles graph diagnostics, and sends the updated graph back to the browser.
 
-Then embed it from a markdown page:
+The editor is implemented as a package extension. Static graph files do not need `HTTP`, but the live editor does. In a project that only depends on `PlantSimEngine`, install `HTTP` first:
 
-```html
-<iframe
-  src="../www/model_graph.html"
-  style="width: 100%; height: 720px; border: 1px solid #d8cfc2; border-radius: 8px;"
-  title="Model dependency graph"
-></iframe>
+```julia
+using Pkg
+Pkg.add("HTTP")
 ```
 
-Use the right relative path for the page where the iframe lives. A page in `docs/src/multiscale/` usually needs `../www/model_graph.html`; a page at the root of `docs/src/` usually needs `www/model_graph.html`.
-
-!!! tip
-    This is the same pattern used to show large package mappings, such as the XPalm dependency graph, directly inside package documentation. The viewer is static, so it works on GitHub Pages without a Julia server.
-
-## Interactive editor
-
-The interactive editor uses the same graph JSON as the static viewer, but it keeps a WebSocket connection open to Julia. Julia remains the source of truth: the browser sends edit commands, Julia applies them to the [`ModelMapping`](@ref), recompiles graph diagnostics, and sends the updated graph back to the browser.
-
-The editor is implemented as a package extension. Load `HTTP` before calling [`edit_graph`](@ref):
+Then load `HTTP` before calling [`edit_graph`](@ref):
 
 ```julia
 using PlantSimEngine
@@ -121,7 +95,7 @@ By default, `edit_graph` opens `session.url` in the system default browser. Pass
 session = edit_graph(mapping; open_browser=false)
 ```
 
-The URL contains a session token and the server listens on `127.0.0.1` by default. Treat that URL as a local capability: anyone who can reach it can edit the live mapping. If you intentionally bind to another host, pass `allow_remote=true` only on a trusted network.
+The URL contains a session token and the server listens on `127.0.0.1` by default. Treat that URL as a local capability: anyone who can reach it can edit the live mapping. If you intentionally bind to another host, pass `allow_remote=true` only on a trusted network. Raw `julia` parameter values are disabled by default for remote sessions; pass `allow_julia_eval=true` only if you explicitly accept that risk.
 
 To stop the HTTP/WebSocket session, run:
 
@@ -227,3 +201,36 @@ available_models(:light_interception)
 ```
 
 If a package is not loaded with `using PackageName`, its model types are not present in the Julia session and the editor cannot list them.
+
+## Embedding a graph in package documentation
+
+For package documentation built with Documenter, generate the HTML file before `makedocs` and place it somewhere under `docs/src`, for example `docs/src/www/model_graph.html`:
+
+```julia
+# docs/make.jl
+using Documenter
+using PlantSimEngine
+using YourPackage
+
+mapping = YourPackage.default_mapping()
+write_graph_view(joinpath(@__DIR__, "src", "www", "model_graph.html"), mapping)
+
+makedocs(;
+    # ...
+)
+```
+
+Then embed it from a markdown page:
+
+```html
+<iframe
+  src="../../www/model_graph.html"
+  style="width: 100%; height: 720px; border: 1px solid #d8cfc2; border-radius: 8px;"
+  title="Model dependency graph"
+></iframe>
+```
+
+Use the right relative path for the page where the iframe lives and remember that Documenter deploys pretty URLs by default. A page in `docs/src/multiscale/page.md` usually needs `../../www/model_graph.html`; a page at the root of `docs/src/` usually needs `www/model_graph.html`.
+
+!!! tip
+    This is the same pattern used to show large package mappings, such as the XPalm dependency graph, directly inside package documentation. The viewer is static, so it works on GitHub Pages without a Julia server.

ext/PlantSimEngineGraphEditorExt.jl

@@ -22,6 +22,7 @@ mutable struct GraphEditorSession{M,G,S} <: PlantSimEngine.AbstractGraphEditorSe
     last_autosaved_path::Union{Nothing,String}
     recent_file_path::String
     recent_mapping_paths::Vector{String}
+    allow_julia_eval::Bool
 end
 
 current_mapping(session::GraphEditorSession) = session.mapping
@@ -48,7 +49,7 @@ end
 current_mapping_code(session::GraphEditorSession) = _model_mapping_to_julia(session.mapping)
 
 """
-    edit_graph([mapping]; mtg=nothing, host="127.0.0.1", port=8765, open_browser=true, autosave=true, allow_remote=false)
+    edit_graph([mapping]; mtg=nothing, host="127.0.0.1", port=8765, open_browser=true, autosave=true, allow_remote=false, allow_julia_eval=nothing)
 
 Start a local graph editor session. The returned session owns the current
 `ModelMapping`; call `current_mapping(session)` to recover the edited mapping.
@@ -59,6 +60,8 @@ By default, the session URL is opened with the system default browser. Pass
 `open_browser=false` to disable this, for example in scripts or tests.
 The URL includes a session token and the server is restricted to localhost
 unless `allow_remote=true` is passed explicitly.
+Raw `julia` parameter values are disabled by default for remote sessions; pass
+`allow_julia_eval=true` only for trusted sessions.
 When `autosave=true`, a recovery script is written to the temporary directory.
 After saving through the web editor, every successful graph edit, undo, redo,
 or recent-file load rewrites the saved Julia script.
@@ -76,6 +79,7 @@ function edit_graph(
     autosave_path::Union{Nothing,AbstractString}=nothing,
     recent_file_path::Union{Nothing,AbstractString}=nothing,
     allow_remote::Bool=false,
+    allow_julia_eval::Union{Nothing,Bool}=nothing,
 )
     if !_is_loopback_host(host) && !allow_remote
         error("Graph editor sessions are limited to localhost by default. Pass `allow_remote=true` only for a trusted network environment.")
@@ -89,6 +93,7 @@ function edit_graph(
     server = HTTP.listen!(handler, host, port; listenany=true, verbose=false)
     actual_port = HTTP.port(server)
     token = _session_token()
+    resolved_allow_julia_eval = isnothing(allow_julia_eval) ? !allow_remote : allow_julia_eval
     session = GraphEditorSession(
         mapping,
         mtg,
@@ -105,6 +110,7 @@ function edit_graph(
         nothing,
         _normalized_output_path(isnothing(recent_file_path) ? _default_recent_file_path() : recent_file_path),
         _load_recent_mapping_paths(isnothing(recent_file_path) ? _default_recent_file_path() : recent_file_path),
+        resolved_allow_julia_eval,
     )
     session_ref[] = session
     _persist_session_mapping!(session; write_save_target=false)
@@ -291,7 +297,7 @@ function _handle_command!(session::GraphEditorSession, command)
             redo!(session)
             persist = true
         elseif action == "edit"
-            edit = _edit_from_command(command)
+            edit = _edit_from_command(session, command)
             apply_edit!(session, edit)
             persist = true
         elseif action == "write_mapping_code"
@@ -311,7 +317,7 @@ function _handle_command!(session::GraphEditorSession, command)
     end
 end
 
-function _edit_from_command(command)
+function _edit_from_command(session::GraphEditorSession, command)
     kind = get(command, "kind", "")
     kind == "mark_previous_timestep" && return PlantSimEngine.MarkPreviousTimeStep(
         Symbol(command["scale"]),
@@ -329,7 +335,7 @@ function _edit_from_command(command)
     )
     if kind == "update_model"
         model_type = _resolve_model_type(command["modelType"])
-        parameters = _parameters_from_command(get(command, "parameters", Dict()))
+        parameters = _parameters_from_command(session, get(command, "parameters", Dict()))
         timestep = _timestep_from_command(get(command, "timestep", nothing); default_sentinel=true)
         return PlantSimEngine.UpdateModel(
             Symbol(command["scale"]),
@@ -352,11 +358,11 @@ function _edit_from_command(command)
     kind == "set_initialization" && return PlantSimEngine.SetStatusVariable(
         Symbol(command["scale"]),
         Symbol(command["variable"]),
-        _parse_parameter_value(get(command, "value", Dict("type" => "julia", "value" => "nothing"))),
+        _parse_parameter_value(session, get(command, "value", Dict("type" => "julia", "value" => "nothing"))),
     )
     if kind in ("add_model", "replace_model")
         model_type = _resolve_model_type(command["modelType"])
-        parameters = _parameters_from_command(get(command, "parameters", Dict()))
+        parameters = _parameters_from_command(session, get(command, "parameters", Dict()))
         timestep = _timestep_from_command(get(command, "timestep", nothing))
         if kind == "add_model"
             return PlantSimEngine.AddModel(Symbol(command["scale"]), model_type, parameters, timestep)
@@ -388,15 +394,15 @@ function _resolve_model_type(label)
     error("No loaded PlantSimEngine model type matches `$label`. Load the package that defines it first.")
 end
 
-function _parameters_from_command(parameters)
+function _parameters_from_command(session::GraphEditorSession, parameters)
     pairs = Pair{Symbol,Any}[]
     for (key, value) in parameters
-        push!(pairs, Symbol(key) => _parse_parameter_value(value))
+        push!(pairs, Symbol(key) => _parse_parameter_value(session, value))
     end
     return (; pairs...)
 end
 
-function _parse_parameter_value(value)
+function _parse_parameter_value(session::GraphEditorSession, value)
     value isa AbstractDict || return value
     choice = Symbol(get(value, "type", "julia"))
     raw = get(value, "value", nothing)
@@ -406,6 +412,7 @@ function _parse_parameter_value(value)
     choice == :symbol && return Symbol(raw)
     choice == :string && return String(raw)
     choice == :nothing && return nothing
+    choice == :julia && !session.allow_julia_eval && error("Raw Julia parameter values are disabled for this graph editor session.")
     choice == :julia && return Core.eval(Main, Meta.parse(String(raw)))
     return raw
 end
@@ -689,7 +696,7 @@ function _model_mapping_to_julia(mapping::PlantSimEngine.ModelMapping)
     required_status_variables = _required_status_variables(mapping)
     println(io, "mapping = ModelMapping(")
     for scale in keys(mapping)
-        println(io, "    :$(scale) => (")
+        println(io, "    $(_symbol_code(scale)) => (")
         items = _scale_items(mapping[scale])
         required = get(required_status_variables, scale, Set{Symbol}())
         for item in items
@@ -823,7 +830,17 @@ function _status_to_code(status::PlantSimEngine.Status, required_variables)
         if name in required_variables
     ]
     isempty(kept) && return nothing
-    return "Status(" * join(("$(first(item)) = $(repr(last(item)))" for item in kept), ", ") * ")"
+    names_code = _tuple_code(_symbol_code.(first.(kept)))
+    values_code = _tuple_code([repr(last(item)) for item in kept])
+    return "Status(NamedTuple{$names_code}($values_code))"
+end
+
+_symbol_code(symbol::Symbol) = repr(symbol)
+
+function _tuple_code(items)
+    values = collect(items)
+    suffix = length(values) == 1 ? "," : ""
+    return "(" * join(values, ", ") * suffix * ")"
 end
 
 function _model_spec_to_code(spec::PlantSimEngine.ModelSpec)
@@ -866,27 +883,27 @@ end
 _mapped_variable_symbol(variable::Symbol) = variable
 _mapped_variable_symbol(variable::PlantSimEngine.PreviousTimeStep) = variable.variable
 
-_mapped_lhs_to_code(variable::Symbol) = string(":", variable)
-_mapped_lhs_to_code(variable::PlantSimEngine.PreviousTimeStep) = "PreviousTimeStep(:$(variable.variable))"
+_mapped_lhs_to_code(variable::Symbol) = _symbol_code(variable)
+_mapped_lhs_to_code(variable::PlantSimEngine.PreviousTimeStep) = "PreviousTimeStep($(_symbol_code(variable.variable)))"
 
 function _mapped_rhs_to_code(rhs::Pair{Symbol,Symbol}, variable::Symbol)
     source_scale = first(rhs)
     source_variable = last(rhs)
     if source_scale == Symbol("")
-        return "(Symbol(\"\") => :$(source_variable))"
+        return "($(_symbol_code(source_scale)) => $(_symbol_code(source_variable)))"
     end
     if source_variable == variable
-        return ":$(source_scale)"
+        return _symbol_code(source_scale)
     end
-    return "(:$(source_scale) => :$(source_variable))"
+    return "($(_symbol_code(source_scale)) => $(_symbol_code(source_variable)))"
 end
 
 function _mapped_rhs_to_code(rhs::AbstractVector{<:Pair{Symbol,Symbol}}, variable::Symbol)
     compact = all(last(i) == variable for i in rhs)
     if compact
-        return "[" * join((":" * string(first(i)) for i in rhs), ", ") * "]"
+        return "[" * join((_symbol_code(first(i)) for i in rhs), ", ") * "]"
     end
-    return "[" * join(("(:$(first(i)) => :$(last(i)))" for i in rhs), ", ") * "]"
+    return "[" * join(("($(_symbol_code(first(i))) => $(_symbol_code(last(i))))" for i in rhs), ", ") * "]"
 end
 
 end

frontend/dist/.vite/manifest.json

@@ -1,11 +1,11 @@
 {
   "index.html": {
-    "file": "assets/index--wMugJW5.js",
+    "file": "assets/index--4z54nN9.js",
     "name": "index",
     "src": "index.html",
     "isEntry": true,
     "css": [
-      "assets/index-Wf_4MG8d.css"
+      "assets/index-DwZ0xeih.css"
     ]
   }
 }

frontend/dist/assets/index--wMugJW5.js frontend/dist/assets/index--4z54nN9.jsfrontend/dist/assets/index--wMugJW5.js renamed to frontend/dist/assets/index--4z54nN9.js

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>PlantSimEngine Dependency Graph</title>
-    <script type="module" crossorigin src="/assets/index--wMugJW5.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Wf_4MG8d.css">
+    <script type="module" crossorigin src="/assets/index--4z54nN9.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DwZ0xeih.css">
   </head>
   <body>
     <div id="root"></div>

frontend/dist/assets/index-DwZ0xeih.css

@@ -555,7 +555,7 @@ export default function App() {
   }, [flowInstance, focusEdge, focusNode, graph.edges, nodeById, nodes, portById]);
 
   return (
-    <main className={`app-shell ${viewMode === "overview" ? "overview-mode" : "detail-mode"} ${candidatePopover ? "has-candidate-popover" : ""} ${cycleBreakMode ? "cycle-break-mode" : ""}`}>
+    <main className={`app-shell ${activePanel ? "has-side-panel" : ""} ${viewMode === "overview" ? "overview-mode" : "detail-mode"} ${candidatePopover ? "has-candidate-popover" : ""} ${cycleBreakMode ? "cycle-break-mode" : ""}`}>
       <section className="graph-panel">
         <div className="topbar graph-workbench">
           <button

frontend/dist/assets/index-Wf_4MG8d.css

@@ -32,11 +32,15 @@ body {
 
 .app-shell {
   display: grid;
-  grid-template-columns: minmax(0, 1fr) 340px;
+  grid-template-columns: minmax(0, 1fr);
   height: 100vh;
   position: relative;
 }
 
+.app-shell.has-side-panel {
+  grid-template-columns: minmax(0, 1fr) 340px;
+}
+
 .graph-panel {
   position: relative;
   min-width: 0;