dohertj2/wwtools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4fcda87ecd5852cc7ef00f55d42878280dc01dc6
wwtools/graccesscli/AGENTS.md
T
Joseph Doherty 32f26272ae Initial commit: Wonderware / System Platform tools and reference 
Five tools under one repo, all docs organized per DOCS-GUIDE.md:

- aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary
  logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands:
  last, tail, range, unread, fields. Stable JSON envelope under --llm-json.
  Build template under lib/build/ for rebuilding aaLogReader.dll.

- aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide
  (Markdown converted from CHM), API reference for the ArchestrA.Toolkit
  namespace, and the Monitor / Watchdog VS sample solutions.

- graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy
  configuration via the ArchestrA GRAccess COM interop. Includes session
  daemon, IPC protocol, and llm-json envelope contract.

- grdb: SQL/DDL exploration of the Galaxy Repository database. DDL
  captures, reusable queries, hierarchy / contained-name <-> tag-name
  translation notes.

- histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL
  linked-server, extension tables, every wwXxx time-domain extension,
  every retrieval mode, alarm/event SQL recipes, REST API. Distilled
  from the 243-page Historian Retrieval Guide.

Root contains:
- CLAUDE.md: thin index pointing into each tool's README.
- DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 18:22:20 -04:00

155 lines
8.8 KiB
Markdown
Raw Blame History

# 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`](GRAccess-DLL-and-DotNet10-Notes.md). Active mutation-path defect tracking lives in [`requirements-mutation-typelib-fix.md`](requirements-mutation-typelib-fix.md).
## Key Documentation
All paths below are relative to this `graccesscli/` folder.
- [`GRAccess-DLL-and-DotNet10-Notes.md`](GRAccess-DLL-and-DotNet10-Notes.md) - local GRAccess DLL, COM registration, architecture, and .NET 10 compatibility findings.
- [`requirements-mutation-typelib-fix.md`](requirements-mutation-typelib-fix.md) - mutation-path COM lifecycle fixes (typelib regression resolved, follow-on defect tracked here).
- [`CLAUDE.md`](CLAUDE.md) - existing detailed agent guide for this CLI.
- [`graccess_documentation.md`](graccess_documentation.md) - full GRAccess Toolkit API reference.
- [`graccess_operations.md`](graccess_operations.md) - GRAccess operations grouped by functional area with page references.
- [`docs/usage.md`](docs/usage.md) - CLI commands, options, session mode, and IPC protocol. Update this whenever user-facing commands change.
- [`docs/llm-integration.md`](docs/llm-integration.md) - LLM-facing operating contract, safety rules, and recommended CLI improvements for System Platform IDE automation.
- [`docs/adding-features.md`](docs/adding-features.md) - checklist for adding commands, dispatcher handlers, capabilities metadata, LLM output, validation, tests, and documentation.
- [`docs/zb-galaxy.md`](docs/zb-galaxy.md) - read-only documentation captured from the live `ZB` galaxy with `graccesscli`.
- [`docs/zb-testmachine.md`](docs/zb-testmachine.md) - deep read-only documentation of the `ZB` `$TestMachine` template family and instances.
- [`docs/template-parsing.md`](docs/template-parsing.md) - read-only workflow for inspecting existing templates such as `TestMachine`.
- [`docs/attribute-parsing.md`](docs/attribute-parsing.md) - detailed workflow for parsing all template attributes and setting families.
- [`docs/script-parsing.md`](docs/script-parsing.md) - workflow for parsing script libraries and object-level scripts.
- [`docs/template-editing.md`](docs/template-editing.md) - end-to-end workflow for safely editing existing templates.
- [`docs/template-instance-editing.md`](docs/template-instance-editing.md) - workflow for creating and editing template instances, areas, engine assignments, and I/O settings.
- [`docs/attribute-editing.md`](docs/attribute-editing.md) - detailed workflow for editing template attributes, UDAs, extensions, and setting families.
- [`docs/script-editing.md`](docs/script-editing.md) - workflow for editing script libraries and script-bearing template content.
- [`usage.md`](usage.md) - compatibility copy of the CLI usage documentation; keep it aligned with [`docs/usage.md`](docs/usage.md) if edited.
- [`docs/README.md`](docs/README.md) - index for CLI documentation stored under `docs/`.
- [`docs/clifx_reference.md`](docs/clifx_reference.md) - local CliFx framework reference.
## Repository Layout
```text
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.
```powershell
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:
```powershell
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.
```powershell
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`](docs/usage.md) and [`CLAUDE.md`](CLAUDE.md) before changing session behavior.
## GRAccess References
The primary API entry point is `GRAccessAppClass`.
Typical flow:
```csharp
GRAccessApp grAccess = new GRAccessAppClass();
IGalaxies galaxies = grAccess.QueryGalaxies(Environment.MachineName);
IGalaxy galaxy = galaxies["GalaxyName"];
galaxy.Login("", "");
// work with galaxy
galaxy.Logout();
```
Object model summary:
```text
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`](graccess_documentation.md) and [`graccess_operations.md`](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:
```powershell
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`](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`](docs/adding-features.md) and update user-facing docs in the same change.
Reference in New Issue View Git Blame Copy Permalink