wwtools/graccesscli/AGENTS.md

AGENTS.md

Guidance for coding agents working in the graccesscli folder.

Project Snapshot

This folder contains graccesscli, a .NET Framework 4.8 x86 CLI for automating AVEVA/Wonderware System Platform Galaxy configuration through the ArchestrA GRAccess COM/.NET interop library.

The important platform constraint is that GRAccess is a 32-bit COM stack. Do not try to directly load the native GRAccess DLL from a .NET 10 x64 process. The current CLI stays on net48, x86, and [STAThread] for COM compatibility.

For the detailed local investigation behind this constraint, read GRAccess-DLL-and-DotNet10-Notes.md. Active mutation-path defect tracking lives in requirements-mutation-typelib-fix.md.

Key Documentation

All paths below are relative to this graccesscli/ folder.

• GRAccess-DLL-and-DotNet10-Notes.md - local GRAccess DLL, COM registration, architecture, and .NET 10 compatibility findings.
• requirements-mutation-typelib-fix.md - mutation-path COM lifecycle fixes (typelib regression resolved, follow-on defect tracked here).
• CLAUDE.md - existing detailed agent guide for this CLI.
• graccess_documentation.md - full GRAccess Toolkit API reference.
• graccess_operations.md - GRAccess operations grouped by functional area with page references.
• docs/usage.md - CLI commands, options, session mode, and IPC protocol. Update this whenever user-facing commands change.
• docs/llm-integration.md - LLM-facing operating contract, safety rules, and recommended CLI improvements for System Platform IDE automation.
• docs/adding-features.md - checklist for adding commands, dispatcher handlers, capabilities metadata, LLM output, validation, tests, and documentation.
• docs/zb-galaxy.md - read-only documentation captured from the live ZB galaxy with graccesscli.
• docs/zb-testmachine.md - deep read-only documentation of the ZB $TestMachine template family and instances.
• docs/template-parsing.md - read-only workflow for inspecting existing templates such as TestMachine.
• docs/attribute-parsing.md - detailed workflow for parsing all template attributes and setting families.
• docs/script-parsing.md - workflow for parsing script libraries and object-level scripts.
• docs/template-editing.md - end-to-end workflow for safely editing existing templates.
• docs/template-instance-editing.md - workflow for creating and editing template instances, areas, engine assignments, and I/O settings.
• docs/attribute-editing.md - detailed workflow for editing template attributes, UDAs, extensions, and setting families.
• docs/script-editing.md - workflow for editing script libraries and script-bearing template content.
• usage.md - compatibility copy of the CLI usage documentation; keep it aligned with docs/usage.md if edited.
• docs/README.md - index for CLI documentation stored under docs/.
• docs/clifx_reference.md - local CliFx framework reference.

Repository Layout

graccesscli/
  ZB.MOM.WW.GRAccess.Cli.slnx
  lib/ArchestrA.GRAccess.dll
  src/ZB.MOM.WW.GRAccess.Cli/
    Program.cs
    Commands/
    GRAccess/
    Infrastructure/
    Protocol/
    Session/
  tests/ZB.MOM.WW.GRAccess.Cli.Tests/

Build And Test

Run commands from this graccesscli folder unless noted otherwise.

dotnet build src/ZB.MOM.WW.GRAccess.Cli/ZB.MOM.WW.GRAccess.Cli.csproj -p:Platform=x86
dotnet test tests/ZB.MOM.WW.GRAccess.Cli.Tests/ZB.MOM.WW.GRAccess.Cli.Tests.csproj -p:Platform=x86
dotnet test tests/ZB.MOM.WW.GRAccess.Cli.Tests --filter "FullyQualifiedName~TestName"

Run the CLI:

dotnet run --project src/ZB.MOM.WW.GRAccess.Cli/ZB.MOM.WW.GRAccess.Cli.csproj -- <args>

Implementation Rules

• Keep the CLI and tests targeting net48 and x86.
• Keep the entry point [STAThread]; GRAccess COM calls must run on an STA thread.
• Route long-lived GRAccess work through the session daemon infrastructure when appropriate.
• All GRAccess COM access in daemon mode must go through Session/StaComThread.cs.
• Keep the GRAccessApp object alive for the lifetime of any GRAccess objects derived from it.
• Check CommandResult.Successful after GRAccess calls. Multi-object calls return CommandResults.
• For object changes, follow CheckOut() -> modify -> Save() -> CheckIn(comment). Skipping CheckIn leaves the object locked in the Galaxy repo.
• Treat GRAccess collections as 1-based unless the API docs prove otherwise.
• Use using ArchestrA.GRAccess; for GRAccess API types.
• Use CliFx command patterns already present in the repo: command classes implement ICommand and use [Command], [CommandParameter], and [CommandOption].
• C# language version is 9.0. init is supported through IsExternalInit.cs; do not use the required keyword.

Session Mode

Session mode keeps a GRAccess connection open in a daemon to avoid expensive reconnects.

graccess session start --galaxy MyGalaxy --node MyNode
graccess <command> --galaxy MyGalaxy
graccess session status --galaxy MyGalaxy
graccess session stop --galaxy MyGalaxy

The daemon uses:

• Session file: %LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\sessions\{galaxy}.json
• Log file: %LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\logs\daemon-{galaxy}.log
• Named pipe: graccess-session-{galaxy}
• Mutex: Global\graccess-session-{galaxy}
• IPC: newline-delimited JSON

See docs/usage.md and CLAUDE.md before changing session behavior.

GRAccess References

The primary API entry point is GRAccessAppClass.

Typical flow:

GRAccessApp grAccess = new GRAccessAppClass();
IGalaxies galaxies = grAccess.QueryGalaxies(Environment.MachineName);
IGalaxy galaxy = galaxies["GalaxyName"];
galaxy.Login("", "");
// work with galaxy
galaxy.Logout();

Object model summary:

GRAccessApp
  IGalaxies -> IGalaxy
    IGalaxySecurity / roles / users
    IgObjects -> ITemplate / IInstance
      IAttributes -> IAttribute
  IToolsets
  IScriptLibraries
  ICommandResults

For exact method signatures, enum names, and page references, use graccess_documentation.md and graccess_operations.md.

Current CLI Query Surface

Galaxy-bound commands route through an active session when one exists, and otherwise fall back to one-shot mode:

graccess object list --galaxy ZB --node . --type instance --pattern '%'
graccess template list --galaxy ZB --node . --pattern '%'
graccess instance list --galaxy ZB --node . --pattern '%'
graccess object attributes --galaxy ZB --node . --name DEV --type instance --configurable

When a session is active, routed commands can omit --node and are dispatched by SessionDaemon.ExecuteCommandAsync through GRAccessCommandDispatcher on the daemon STA thread. GRAccess namedLike patterns use % as the wildcard. Attribute metadata should be read defensively because some COM-backed properties can throw when storage is unavailable; unavailable JSON fields are represented as null.

The expanded CLI surface is concentrated in Commands/GRAccessSurfaceCommands.cs and routes through GRAccess/GRAccessCommandDispatcher.cs. Mutating commands must pass --confirm and matching --confirm-target; keep that guard in place for delete, deploy, restore, migrate, import, GRLoad, and object configuration changes.

LLM-facing automation is documented in docs/llm-integration.md. Preserve legacy --json shapes; use --llm-json for stable envelopes. Keep capabilities, validate, batch, object snapshot, attribute value commands, object script commands, and area/engine/I/O wrappers aligned with CommandCapabilityRegistry.

For deep read-only parsing, prefer object snapshot, object lineage, and object children with --llm-json. These commands should use direct GRAccess typed reads first and may use temporary GRAccess-exported package parsing for lineage, contained objects, attribute values, and script bodies when direct COM properties are unavailable. Normal CLI behavior must not query the Galaxy Repository SQL database; SQL access is development verification/debugging only.

When adding new CLI features, follow docs/adding-features.md and update user-facing docs in the same change.