From 87c0124174cf84fe650c73c27ce1dcf447aa412d Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 5 May 2026 16:40:55 -0400 Subject: [PATCH] Clarify script mutation limits --- graccesscli/docs/llm-integration.md | 4 +- graccesscli/docs/script-editing.md | 23 +++++---- graccesscli/docs/usage.md | 7 +-- graccesscli/docs/zb-testmachine.md | 2 +- .../Commands/GRAccessSurfaceCommands.cs | 10 ++-- .../GRAccess/GRAccessCommandDispatcher.cs | 3 ++ .../Commands/GRAccessSurfaceCommandTests.cs | 48 +++++++++++++++++++ 7 files changed, 76 insertions(+), 21 deletions(-) diff --git a/graccesscli/docs/llm-integration.md b/graccesscli/docs/llm-integration.md index 7e67052..a9ba672 100644 --- a/graccesscli/docs/llm-integration.md +++ b/graccesscli/docs/llm-integration.md @@ -60,7 +60,7 @@ graccess object scripts get --galaxy ZB --name TestMachine --type template --scr The CLI tries direct GRAccess reads first. If direct GRAccess does not expose inheritance, attribute values, or script bodies, read commands may export the target object to a temporary `.aaPKG`, parse textual/package entries, recurse into nested package archives, parse binary UTF-16 script extension records, and delete the temp files. SQL Server repository reads are not part of normal CLI behavior and should only be used for development verification/debugging. -Script body access is adapter-dependent. For `ScriptExtension` objects, a bare script name maps to `.ExecuteText`; `object scripts set` writes the matching script body attribute through GRAccess. Mutating script and attribute commands prefer `ConfigurableAttributes[...]` before `Attributes[...]`, because script extension settings such as `TriggerPeriod`, `TriggerType`, `Expression`, and `ExecuteText` are configuration attributes in common GRAccess builds. If neither direct GRAccess nor the package fallback exposes body text, script read commands return structured unavailable details instead of pretending success. +Script body access is adapter-dependent. For `ScriptExtension` objects, a bare script name maps to `.ExecuteText`. Mutating script and attribute commands prefer `ConfigurableAttributes[...]` before `Attributes[...]`. On the local GRAccess build, body fields such as `ExecuteText` and `Expression` are package-only and are not persisted by `IAttribute.SetValue`, so the CLI fails fast for those writes instead of returning a false success. Mutable settings such as `TriggerPeriod` and `TriggerType` remain available through `object scripts settings set`. If neither direct GRAccess nor the package fallback exposes body text, script read commands return structured unavailable details instead of pretending success. Use the script settings wrapper for IDE-style script configuration: @@ -71,7 +71,7 @@ graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type te Use the create wrapper for new object-level script extensions: ```powershell -graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file OnScan.txt --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json +graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json ``` ## Inheritance And Embedded Objects diff --git a/graccesscli/docs/script-editing.md b/graccesscli/docs/script-editing.md index 9e00b34..1571609 100644 --- a/graccesscli/docs/script-editing.md +++ b/graccesscli/docs/script-editing.md @@ -17,7 +17,7 @@ For LLM-driven script work, read script metadata and validate guarded edits with ```powershell graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json -graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --dry-run --llm-json +graccess object scripts settings set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --trigger-period-ms 500 --confirm --confirm-target TestMachine --dry-run --llm-json ``` ## What The CLI Can Edit Today @@ -28,7 +28,8 @@ graccess object scripts set --galaxy ZB --name TestMachine --type template --scr | Script library export | `script-library export` | | Script library import/add | `script-library import`, `script-library add`, `galaxy import-script-library` | | Object script metadata | `object scripts list`, `object scripts get` | -| Object script body read/write | `object scripts get`, `object scripts set` for script body attributes such as `ExecuteText` | +| Object script body read | `object scripts get` package fallback for script body attributes such as `ExecuteText` | +| Object script mutable settings | `object scripts settings set --trigger-type`, `--trigger-period-ms` | | Script-like attributes | `object attribute set`, lock, security, buffer | | Extension primitives | `object extension add/delete/rename` | | Full object package script payloads | Use `objects export` and `galaxy import-objects` | @@ -90,13 +91,15 @@ $scripts = (@($attrs) + @($extended)) | Where-Object { $scripts | Select-Object Name, DataType, Category, Locked ``` -If the script-like setting is a scalar string attribute, edit it through the normal template edit flow. Script extension fields should be written through `ConfigurableAttributes`; the CLI does this automatically for `object scripts set`, `object scripts settings set`, and mutating `object attribute` commands. `object scripts set` is the convenience wrapper for script body attributes. A bare script name maps to `.ExecuteText`; explicit fields such as `.StartupText`, `.OnScanText`, or `.Expression` are preserved. +If the script-like setting is a scalar writable attribute, edit it through the normal template edit flow. Script extension attributes are looked up through `ConfigurableAttributes` first, then `Attributes`. + +For local `ScriptExtension` objects, body fields such as `ExecuteText`, `StartupText`, `OnScanText`, and `Expression` are package-only. GRAccess `IAttribute.SetValue` can return success without persisting package-only fields, so `object scripts set` and `object scripts settings set --expression` fail fast when the attribute category starts with `MxCategoryPackageOnly`. Use the IDE or a future package-rewrite path for those fields. ```powershell graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine -graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine +graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute SomeWritableScriptSetting --value Updated --data-type string --confirm --confirm-target TestMachine graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine -graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Update script text' --confirm --confirm-target TestMachine +graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Update writable script setting' --confirm --confirm-target TestMachine ``` Update periodic script settings and lock the interval for deployment inheritance: @@ -137,16 +140,16 @@ Delete: graccess object extension delete --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan2 --object-extension --confirm --confirm-target TestMachine ``` -These commands manage primitive structure. The IDE-oriented wrapper below creates the same `ScriptExtension` primitive and can initialize the body and common settings: +These commands manage primitive structure. The wrapper below creates the same `ScriptExtension` primitive and can initialize mutable settings: ```powershell graccess object checkout --galaxy ZB --name '$MyTemplate' --type template --confirm --confirm-target '$MyTemplate' -graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file .\OnScan.txt --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' +graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' graccess object save --galaxy ZB --name '$MyTemplate' --type template --confirm --confirm-target '$MyTemplate' graccess object checkin --galaxy ZB --name '$MyTemplate' --type template --comment 'Add OnScan script' --confirm --confirm-target '$MyTemplate' ``` -After adding a `ScriptExtension` primitive, set its body with `object scripts set --script ` or `object scripts set --script .ExecuteText`. +After adding a `ScriptExtension` primitive, body text still needs the IDE/package path when the projected body attributes are package-only. ## Full-Fidelity Object Script Edits @@ -200,7 +203,7 @@ graccess instance deploy --galaxy ZB --name TestMachine_ScriptTest_001 --type in ```text graccess object scripts list --galaxy ZB --name TestMachine --type template --json graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json -graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --llm-json +graccess object scripts settings set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --trigger-period-ms 500 --confirm --confirm-target TestMachine --llm-json ``` -The local GRAccess examples sometimes show `Template.Scripts[index].ScriptString`. This repository's installed interop exposes the same practical content through script extension attributes such as `UpdateTestChangingInt.ExecuteText`; the CLI writes those attributes directly via `IAttribute.SetValue`. +The local GRAccess examples sometimes show `Template.Scripts[index].ScriptString`, but this repository's installed `ArchestrA.GRAccess.dll` does not expose a public object script collection. It exposes script extension projections as attributes and package records. The CLI can read body text through exported package parsing and can write mutable settings through `IAttribute.SetValue`; package-only body/expression fields are not persisted by that GRAccess setter. diff --git a/graccesscli/docs/usage.md b/graccesscli/docs/usage.md index aa28df1..b55e394 100644 --- a/graccesscli/docs/usage.md +++ b/graccesscli/docs/usage.md @@ -242,14 +242,15 @@ Scalar `string`, `bool`, `int`, `float`, and `double` writes are supported first graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt.ExecuteText --llm-json -graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --llm-json graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type template --script UpdateTestChangingInt --trigger-period-ms 500 --lock-trigger-period --confirm --confirm-target '$TestMachine' --llm-json -graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file OnScan.txt --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json +graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json ``` Direct object script body access depends on the local GRAccess object model. Reads inspect the exported package fallback for script extension bodies and script text fields such as `ExecuteText`, `DeclarationsText`, `StartupText`, `ShutdownText`, `OnScanText`, `OffScanText`, and `Expression`. -For writes, the CLI follows the GRAccess pattern used by `ScriptExtension` objects: script body and setting mutations prefer `IgObject.ConfigurableAttributes[...]`, then fall back to `Attributes[...]` only if the configurable collection does not expose the requested field. `object scripts set` writes the matching script body attribute; a bare script name maps to `.ExecuteText`. `object scripts settings set` writes common script settings such as `TriggerPeriod`, `TriggerType`, and `Expression`; `--lock-trigger-period` applies `MxLockedInMe` so derived instances receive the interval on deploy. `object scripts create` calls `AddExtensionPrimitive("ScriptExtension",