diff --git a/docs/plugin-host-model-completion-plan.md b/docs/plugin-host-model-completion-plan.md index fc5037976..d861fe9e7 100644 --- a/docs/plugin-host-model-completion-plan.md +++ b/docs/plugin-host-model-completion-plan.md @@ -9,7 +9,7 @@ Build a general Python document model over the OCS host API so a script can cont - **Entities:** explicit writes for all 43 canvas kinds (41 creatable; the legacy `Polyline` and `Body` are update-only). **31 kinds are `Complete`** (every C/R/E/D/U/I/W/V/P gate passes). The remaining kinds are integration-tested and held short of `Complete` by a named blocker in the ledger: seven by cadcodec DXF bugs (fixes submitted as [cadcodec#48](https://github.com/HakanSeven12/cadcodec/pull/48), not yet merged, so OCS still pins the unfixed revision), Polyline3D by the DWG format, Polyline2D by a kind change on DXF save, RasterImage by an image-reactor structure that cannot be verified, and Body by having no creation path. - **Drawing tables:** layers, text and dimension styles, blocks and their contents, linetypes and layouts, through the additive `TableOperation` request (see the log entries dated 2026-09-21). - **Commands:** `HostApi::run_command` drives the real OCS commands step by step; `doc.command`, `doc.start_command` and `doc.modify` build on it. -- **Known open items:** the unfiled cadcodec findings (`cadcodec-reader-gaps.md`), complex (text and shape) linetypes, plot devices and named page setups, PEDIT's remaining options, and an on/off setting for script-driven commands. +- **Known open items:** the unfiled cadcodec findings (`cadcodec-reader-gaps.md`), complex (text and shape) linetypes, plot devices and named page setups, and PEDIT's remaining options. Repositories: @@ -302,3 +302,21 @@ step needs between 2 and 4 MiB of stack in a debug build, more than a test threa application's main thread has 8 MiB, and a release build uses far less. Not wrapped: PEDIT fit, spline, decurve, linetype generation and vertex editing. +### 2026-09-21: guardrails (`SCRIPTCOMMANDS`, stack) + +**On/off setting.** A saved user preference, `UserSettings::script_commands` (on by default, so an existing config keeps +scripts allowed), toggled by the `SCRIPTCOMMANDS [0|1]` command, gates `HostApi::run_command`: while it is off every `Run`, +`Start` and input request is refused (`Cancel` stays allowed so a waiting command is never stranded) with a message that says how to turn it back on. The runner refuses the command +itself (it joins `QUIT`, `NEW`, `PY_*` and the rest on the denylist), so a script cannot switch it. It is a command and a +persisted flag only; there is no Options-page control, which would need locale and layout work in files outside this feature. +Evidence: `script_commands_setting_gates_the_runner` (default on; a script cannot change it; the user turns it off and nothing +runs, `Run` and `Start` both refused, no entity added; back on and it runs) and `script_commands_default_on_and_survive_a_round_trip`. +Checked that the test did not write the setting into the real user config. + +**Stack.** The planned large-stack thread for command steps was not built, on the evidence: the native builds already link with +at least 8 MiB (`.cargo/config.toml` raises Windows to 16 MiB), the deepest step found (PEDIT converting a line to a polyline) +needs 2 to 4 MiB in a debug build, and the nesting depth is fixed because `PY_*` is refused, so it cannot recurse. Moving the step +to a helper thread would be unsound here (the editor state is not `Send` and some of it has thread affinity), and the alternative, +a stack-growing dependency such as `stacker`, adds a crate to H7's tree to guard a case that cannot occur. The 64 MiB thread in the +PEDIT audit stays, because a test thread gets only 2 MiB. + diff --git a/docs/plugin-host-model.md b/docs/plugin-host-model.md index 76a7758f6..d010baf6f 100644 --- a/docs/plugin-host-model.md +++ b/docs/plugin-host-model.md @@ -96,11 +96,14 @@ to arrive from outside; an earlier fire-and-forget replay could hang, this does Guards: refused while another command is active or off the active tab; refused for commands that could end the session or re-enter Python (`QUIT`, `EXIT`, `CLOSE*`, -`NEW`, `QNEW`, `OPEN`, `SAVE*`, `RECOVER`, `SCRIPT`, `RUNSCRIPT`, `PY_*`); an editor or -dialog a command opens is reported and closed by `Cancel`. It does not consult the -automation on/off switch, which governs the external MCP and serve channels; a script -is something the user chose to run. The Python layer cancels any step sequence that -leaves a command waiting. +`NEW`, `QNEW`, `OPEN`, `SAVE*`, `RECOVER`, `SCRIPT`, `RUNSCRIPT`, `SCRIPTCOMMANDS`, `PY_*`); an editor or +dialog a command opens is reported and closed by `Cancel`. The user can turn the whole +facility off with the saved `SCRIPTCOMMANDS` preference (on by default; `SCRIPTCOMMANDS 0` +at the command line): while it is off, every request except `Cancel` is refused (so a command a script left +waiting can still be closed). A script cannot change +it, because the runner refuses that command. The runner does not consult the automation +on/off switch, which governs the external MCP and serve channels. The Python layer cancels +any step sequence that leaves a command waiting. ## Python surface @@ -126,8 +129,8 @@ as `{"type": "overflow", "dropped": n}`. Tokens are bound to the tab that asked. descriptions, a dimension style's text-style name) and mis-scales one angle; these are pinned by canaries and listed in `cadcodec-reader-gaps.md`. - Not available from a script: complex (text and shape) linetypes, plot devices and named - page setups, PEDIT's fit and spline options, interactive-only commands such as HATCH, and - a setting to turn script-driven commands off. -- A command step nests inside the editor's message handling; in a debug build a deep step - (PEDIT converting a line to a polyline) needs more than 2 MiB of stack, which the - application's 8 MiB main thread provides and a release build needs far less of. + page setups, PEDIT's fit and spline options, and interactive-only commands such as HATCH. +- A command step nests inside the editor's message handling. In a debug build a deep step + (PEDIT converting a line to a polyline) needs between 2 and 4 MiB of stack; the native + builds link with at least 8 MiB (16 MiB on Windows, `.cargo/config.toml`), the nesting depth + is fixed rather than recursive (`PY_*` is refused), and a release build uses far less. diff --git a/plugins/opencad-python/PLUGIN.md b/plugins/opencad-python/PLUGIN.md index 28ed53c53..4394d47d6 100644 --- a/plugins/opencad-python/PLUGIN.md +++ b/plugins/opencad-python/PLUGIN.md @@ -312,9 +312,13 @@ points default to the middle of a line, arc or circle and the first vertex of a undone as the editor would undo it. Guards: a command is refused while another is active (cancel it first) or when the -line names a command that could end the session or re-enter Python: `QUIT`, -`EXIT`, `CLOSE`, `CLOSEALL`, `NEW`, `QNEW`, `OPEN`, `SAVE`, `QSAVE`, `SAVEAS`, `SAVEALL`, -`RECOVER`, `SCRIPT`, `RUNSCRIPT` and any `PY_*`. Commands run on the active +line names a command that could end the session, re-enter Python or change this +setting: `QUIT`, `EXIT`, `CLOSE`, `CLOSEALL`, `NEW`, `QNEW`, `OPEN`, `SAVE`, `QSAVE`, +`SAVEAS`, `SAVEALL`, `RECOVER`, `SCRIPT`, `RUNSCRIPT`, `SCRIPTCOMMANDS` and any `PY_*`. +The user can switch the whole facility off with the `SCRIPTCOMMANDS 0` command (`1` +turns it back on, plain `SCRIPTCOMMANDS` shows it); it is a saved preference, on by +default, and while it is off every `doc.command`, `start_command` and `doc.modify` call +raises `RuntimeError`. Only the command line can change it, never a script. Commands run on the active document only. Commands that need an interactive surface a script cannot fill (the rich-text editor, a file dialog) report it in `blocked_by` and are cancelled. PEDIT's fit, spline, decurve and vertex-edit options are not wrapped (reach them with diff --git a/src/app/commands/styleprops.rs b/src/app/commands/styleprops.rs index 67353d6f8..1c3906ce6 100644 --- a/src/app/commands/styleprops.rs +++ b/src/app/commands/styleprops.rs @@ -2894,6 +2894,25 @@ impl OpenCADStudio { _ => self.command_line.push_error(crate::t!("Requires 0 or 1").as_ref()), } } + cmd if cmd == "SCRIPTCOMMANDS" || cmd.starts_with("SCRIPTCOMMANDS ") => { + // A user setting, deliberately outside the script's reach: it is refused by + // the script command runner, so only the command line can change it. + let arg = cmd.trim_start_matches("SCRIPTCOMMANDS").trim(); + match arg { + "" => {} + "1" | "ON" | "YES" => self.script_commands = true, + "0" | "OFF" | "NO" => self.script_commands = false, + _ => { + self.command_line.push_error("SCRIPTCOMMANDS takes 1 (scripts may run commands) or 0 (they may not)"); + return Some(Task::none()); + } + } + if !arg.is_empty() { + self.persist_settings_if_changed(); + } + let state = if self.script_commands { 1 } else { 0 }; + self.command_line.push_output(&format!("SCRIPTCOMMANDS = {state}")); + } "SAVETIME" => { use crate::command::ValuePromptCommand; let c = ValuePromptCommand::new( diff --git a/src/app/mod.rs b/src/app/mod.rs index 16b77c3cb..ab5d279b2 100644 --- a/src/app/mod.rs +++ b/src/app/mod.rs @@ -616,6 +616,8 @@ pub(super) struct OpenCADStudio { /// Minutes between autosaves to a `.sv$` recovery file (SAVETIME command); /// 0 disables autosave. pub savetime_min: i32, + /// SCRIPTCOMMANDS: scripts may run OCS commands (see `UserSettings`). + pub script_commands: bool, /// Persisted default viewport background, restored from settings and applied /// to every drawing tab (new and opened) so a chosen background survives /// restarts (#188). `None` = the built-in dark-grey / off-white defaults. @@ -3956,6 +3958,7 @@ impl OpenCADStudio { constraint_bar_display: 3, constraint_bar_mode: 4095, savetime_min: 10, + script_commands: true, default_bg_color: None, default_paper_bg_color: None, cliprompt_lines: 3, diff --git a/src/app/plugin_host.rs b/src/app/plugin_host.rs index 6f56798df..658990381 100644 --- a/src/app/plugin_host.rs +++ b/src/app/plugin_host.rs @@ -1291,7 +1291,7 @@ impl<'a> HostSession<'a> { let first = line.split_whitespace().next()?.trim_start_matches(['\'', '_']).to_uppercase(); const DENIED: &[&str] = &[ "QUIT", "EXIT", "CLOSE", "CLOSEALL", "NEW", "QNEW", "OPEN", "SAVE", "QSAVE", "SAVEAS", - "SAVEALL", "RECOVER", "SCRIPT", "RUNSCRIPT", + "SAVEALL", "RECOVER", "SCRIPT", "RUNSCRIPT", "SCRIPTCOMMANDS", ]; if DENIED.contains(&first.as_str()) || first.starts_with("PY_") { Some(format!("the command {first} cannot be run from a script")) @@ -1299,6 +1299,11 @@ impl<'a> HostSession<'a> { None } }; + // Cancel stays allowed: if the user turns scripts off mid-run, a command a script left + // waiting must still be closable rather than stranded. + if !self.app.script_commands && !matches!(request, R::Cancel) { + return Err("running commands from a script is turned off (SCRIPTCOMMANDS = 0); turn it on at the command line with SCRIPTCOMMANDS 1".to_owned()); + } let active = self.app.tabs[tab].active_cmd.is_some(); let before = self.document().entities().count() as i64; let error_revision = self.app.command_line.error_revision; @@ -8265,6 +8270,39 @@ step('undo_move', lambda: M.move([u], (0, 0, 0), (7, 0, 0))) drop(process); } + /// The user's SCRIPTCOMMANDS setting gates the command runner, and a script cannot change it. + #[test] + fn script_commands_setting_gates_the_runner() { + use ocs_plugin_api::host::CommandRequest as R; + let mut app = OpenCADStudio::new_for_test(); + app.tabs[0].is_start = false; + assert!(app.script_commands, "scripts may run commands by default"); + let run = |app: &mut OpenCADStudio, line: &str| HostSession::new(app, 0).run_command(R::Run { line: line.into() }); + assert!(run(&mut app, "LINE 0,0 10,0").is_ok()); + + // A script cannot touch the setting, on or off. + let refused = run(&mut app, "SCRIPTCOMMANDS 0").unwrap_err(); + assert!(refused.contains("cannot be run from a script"), "{refused}"); + assert!(app.script_commands); + + // The user turns it off at the command line. + let reply = app.automation_op(r#"{"op":"run","cmd":"SCRIPTCOMMANDS 0"}"#); + assert_eq!(reply["ok"], true, "{reply}"); + assert!(!app.script_commands); + let refused = run(&mut app, "LINE 0,0 20,0").unwrap_err(); + assert!(refused.contains("turned off"), "{refused}"); + let refused = HostSession::new(&mut app, 0).run_command(R::Start { name: "LINE".into() }).unwrap_err(); + assert!(refused.contains("turned off"), "{refused}"); + assert_eq!(app.tabs[0].scene.document.entities().count(), 1, "nothing ran while it was off"); + assert!(HostSession::new(&mut app, 0).run_command(R::Cancel).is_ok(), "Cancel is still allowed while it is off"); + + // And back on. + app.automation_op(r#"{"op":"run","cmd":"SCRIPTCOMMANDS 1"}"#); + assert!(app.script_commands); + assert!(run(&mut app, "LINE 0,0 20,0").is_ok()); + assert_eq!(app.tabs[0].scene.document.entities().count(), 2); + } + /// Exploration harness (not a gate): prints how the real commands answer /// each step so the wrappers are written against observed prompts. #[test] diff --git a/src/app/settings.rs b/src/app/settings.rs index 938189196..ddbb07fe9 100644 --- a/src/app/settings.rs +++ b/src/app/settings.rs @@ -476,6 +476,10 @@ pub struct UserSettings { /// Minutes between autosaves to a `.sv$` recovery file (SAVETIME command). /// 0 disables autosave. pub savetime_min: i32, + /// SCRIPTCOMMANDS: whether a script (the Python plugin) may run OCS commands + /// through the host. On by default; a user turns it off with the + /// `SCRIPTCOMMANDS 0` command, and a script cannot change it. + pub script_commands: bool, /// File type and version used when a new/unsaved drawing is first saved. /// Existing drawings keep their own type and version. pub default_save_format: String, @@ -676,6 +680,7 @@ impl Default for UserSettings { constraint_bar_display: 3, constraint_bar_mode: 4095, savetime_min: 10, + script_commands: true, default_save_format: crate::io::DEFAULT_SAVE_FORMAT.to_string(), pick_add: true, pick_drag_rect: false, @@ -789,6 +794,19 @@ mod tests { assert_eq!(cfg.settings.savetime_min, 42); } + #[test] + fn script_commands_default_on_and_survive_a_round_trip() { + let missing: crate::app::config::AppConfig = + serde_json::from_str(r#"{"settings": {"pick_add": false}}"#).unwrap(); + assert!(missing.settings.script_commands, "an old config keeps scripts allowed"); + let off: crate::app::config::AppConfig = + serde_json::from_str(r#"{"settings": {"script_commands": false}}"#).unwrap(); + assert!(!off.settings.script_commands); + let text = serde_json::to_string(&off).unwrap(); + let back: crate::app::config::AppConfig = serde_json::from_str(&text).unwrap(); + assert!(!back.settings.script_commands); + } + #[test] fn isometric_drafting_never_persists_or_loads() { // A persisted On used to bring the isoplane crosshair (vertical + diff --git a/src/app/update/file.rs b/src/app/update/file.rs index bb43488b2..2a7c25a35 100644 --- a/src/app/update/file.rs +++ b/src/app/update/file.rs @@ -619,6 +619,7 @@ impl OpenCADStudio { constraint_bar_display: self.constraint_bar_display, constraint_bar_mode: self.constraint_bar_mode, savetime_min: self.savetime_min, + script_commands: self.script_commands, default_save_format: self.default_save_format.clone(), pick_add: self.pick_add, pick_drag_rect: self.pick_drag_rect, @@ -723,6 +724,7 @@ impl OpenCADStudio { self.constraint_bar_display = s.constraint_bar_display.clamp(0, 3); self.constraint_bar_mode = s.constraint_bar_mode.clamp(0, 4095); self.savetime_min = s.savetime_min; + self.script_commands = s.script_commands; self.default_save_format = crate::io::canonical_save_format(&s.default_save_format).to_string(); self.pick_add = s.pick_add;